Application perspective

Implicit initialization and shutdown

When a developer exports a new symbol as part of the HDF5 library, they should make sure that an application cannot enter the library in an uninitialized state through a new API function, or read an uninitialized value from a non-function HDF5 symbol.

The HDF5 library initializes itself when an application either enters the library through an API function call such as H5Fopen, or when an application evaluates an HDF5 symbol that represents either a property-list identifier such as H5F_ACC_RDONLY or H5F_ACC_RDWR, a property-list class identifier such as H5P_FILE_ACCESS, a VFD identifier such as H5FD_FAMILY or H5FD_SEC2, or a type identifier such as H5T_NATIVE_INT64.

The library sets a flag when initialization occurs and as long as the flag is set, skips initialization.

The library provides a couple of macros that initialize the library as necessary. The library is initialized as a side-effect of the FUNC_ENTER_API* macros used at the top of most API functions. HDF5 library symbols other than functions are provided through #defines that use H5OPEN to introduce a library-initialization call (H5open) at each site where a non-function symbol is used.

Ordinarily the library registers an atexit(3) handler to shut itself down when the application exits.

Explicit initialization and shutdown

An application may use an API call, H5open, to explicitly initialize the library. H5close explicitly shuts down the library.

Library internals perspective

No matter how library initialization begins, eventually the internal function H5_init_library will be called. H5_init_library is responsible for calling the initializers for every internal HDF5 library module (aka "package") in the correct order so that no module is initialized before its prerequisite modules. A table in H5_init_library establishes the order of initialization. If a developer adds a module to the library that it is appropriate to initialize with the rest of the library, then they should insert its initializer into the right place in the table.

H5_term_library drives library shutdown. Library shutdown is table-driven, too. If a developer adds a module that needs to release resources during library shutdown, then they should add a call at the right place to the shutdown table. Note that some entries in the shutdown table are marked as "barriers," and if a new module should only be shutdown strictly after the preceding modules, then it should be marked as a barrier. See the comments in H5_term_library for more information.