summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/library-init-shutdown.md56
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.