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.

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.

Tests