.. ====================================================================== CHLone - CGNS HDF5 LIBRARY only node edition See license.txt in the root directory of this source release ====================================================================== .. _implement:: Implementation ============== The CGNS/HDF5 file mapping details the implementation of the SIDS data structure but it doesn't explain the run-time behaviour of a library. This section gives the implementation choices and limitations that would impact an application using CHLone. CHLone design ------------- C1 interface ------------ The purpose of C1 is to allow people to reuse their existing applications without modification. A simple relink of the executable program would be enough to change the CGNS/MLL implementation to CHLone. Then, the idea of C1 really is this compatibility. This leads to implementation choices we wouldn't have made in other context. First, we have to use global variables. The context reference uses an integer which is no more than a table index. This table has to be global. The modification of the table is protected by mutexes, but this is not that useful because: 1. CGNS/MLL application are not supposed to run with threads 2. Many goto-context functions of CGNS/MLL require a global variable The goto-context functions assume there is a current global context, the fonction interface even lack the context argument:: cg_link_write(localnode,targetfile,targetnode); There is no way to keep the same interface without a global variable. The choice is to set the global current context in the cg_goto function. Another point is the index management. Each creation of a CGNS/MLL object returns an index. This index can be used to refer to this object in the next CGNS/MLL call:: int B; cg_base_write(fn,"Base",3,3,&B); cg_base_read(fn,B); This index, again, is the entry number in a table. The index lifetime is the context (the fn argument) lifetime. As CHLone is not supposed to buffer anything, we avoid storing node ids in tables, the index is the position of the actual HDF5 node in its children list. We force HDF5 to track this order by using the creation time as the sort criteria in the children list. However, such a criteria has to be set at the file creation time, it cannot be used on already existing files. Profiling +++++++++ Test coverage +++++++++++++ To perform the coverage, you have to run:: scons clean scons tests coverage=1 The result is in `doc/coverage.txt`. Any other command or intermediate target would not produce the expected report and would to errors such as:: .scons.linux2.tmp/build/src/l3.gcda:stamp mismatch with graph file or any other weird gcov errors. The coverage report is generated into the top directory, to include it into the actual docs you have to run the doc generation. The `*.gcov` files you find into the top directory are the annotated source files. You can then check which branches of the code were not reached by the test suite. .. toctree:: CHLone-coverage Miscellaneous ------------- Transactional features ++++++++++++++++++++++ So far, there is no transactional or recovery features. A crash would be managed by the application using HDF5 interface features. A complex operation that fails, i.e. A long copy or a long move on linked-to files, would have no rollback. Thus the actual state of the HDF5 files would be an intermediate state between no action and the action completed. Fortran vs C ordering in data arrays ++++++++++++++++++++++++++++++++++++ CHLone defines the version with the `[ hdf5version]` attribute, which replaces the old `[ version]` attribute. This implies there is no dimension swap at read/write in the l3 layer. The SIDS/HDF5 file mapping defines the flags attribute. One of the flags indicates wether the ordering is C or Fortran. See annex about these ordering concerns. MPI-based parallel applications +++++++++++++++++++++++++++++++ An application using MPI has no impact on CHLone. MPI applications can have separate contextes. Multi-threading applications ++++++++++++++++++++++++++++ The CHLone library allows the use of multi-threading. First it is threadsafe, this means you can run CHLone calls in different threads, CHLone actually serializes the calls so that it insures no data corruption or race conditions. However, CHLone cannot manage the data consistency at the application level. These can share the same context and CHLone cannot insure that an asynchroneous suite of read and writes are leading to a correct behaviour for your application. Link traversal policy +++++++++++++++++++++ A link is a reference to another node. The current node data is silently replaced by the linked-to node. Using links allows you to share data, such as large meshes for example, or it allows you to refer to a node that doesn't exist yet. For example you can build a skeletton of a result file, with links to the expected CGNS files produced at the end of a simulation. The use of links leads to some behaviour problems, for example when you modify, delete, copy or move a node. 1. A recursive parse of a file is stopped if a link cannot be solved, e.g. If the linked-to file is not found or not readable, or if the linked-to node doesn't exist in the linked-to file. If the flag L3_F_FAILSONLINK is set to OFF, the unresolved link is ignored, the link node doesn't appear in the child list of its parent node and the recursive parse is resumed. 2. A node delete is recursively propagated unless the L3_F_FOLLOWLINKS is OFF. If, during the recursion, a read-only file is found, the recursion is stopped. If the flag L3_F_FAILSONLINK is set to OFF, the deletion is resumed. 3. A node copy is recursively propagated unless the L3_F_FOLLOWLINKS is OFF. When the copy finds a node into another file, the copy is made in the initial file of the copy, not into the linked-to file. 4. A node modification implies a write access to the actual file of the node. If the actual file is read-only the modification fails and an error is raised unless the flag L3_F_FAILSONLINK is set to OFF. In that case, the modification is resumed. .. raw:: html
Tests +++++