diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/library-init-shutdown.md | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/doc/library-init-shutdown.md b/doc/library-init-shutdown.md new file mode 100644 index 0000000..917d213 --- /dev/null +++ b/doc/library-init-shutdown.md @@ -0,0 +1,56 @@ +# HDF5 Library initialization and shutdown + +## 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 `#define`s +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 initializion 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. |