1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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.
|
