summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>2018-03-27 19:20:32 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>2018-03-27 19:20:32 (GMT)
commit711ac55f9648d21b0cfbdda24366773de5199af5 (patch)
tree2d30bdf8080193e98446a1cd3a21ac0beaae8e08
parent6303e24a2fe22e5e25638a59071c7cdfcf85a941 (diff)
downloadhdf5-711ac55f9648d21b0cfbdda24366773de5199af5.zip
hdf5-711ac55f9648d21b0cfbdda24366773de5199af5.tar.gz
hdf5-711ac55f9648d21b0cfbdda24366773de5199af5.tar.bz2
Add comments for internal structs.
-rw-r--r--src/H5CX.c48
1 files changed, 44 insertions, 4 deletions
diff --git a/src/H5CX.c b/src/H5CX.c
index 3a2fae3..f335e38 100644
--- a/src/H5CX.c
+++ b/src/H5CX.c
@@ -146,7 +146,35 @@
/* Local Typedefs */
/******************/
-/* Context stored for each API call */
+/* Typedef for context about each API call, as it proceeds */
+/* Fields in this struct are of several types:
+ * - The DXPL & LAPL ID are either library default ones (from the API context
+ * initialization) or passed in from the application via an API call
+ * parameter. The corresponding H5P_genplist_t* is just the underlying
+ * property list struct for the ID, to optimize retrieving properties
+ * from the list multiple times.
+ *
+ * - Internal fields, used and set only within the library, for managing the
+ * operation under way. These do not correspond to properties in the
+ * DXPL or LAPL.
+ *
+ * - Cached properties, which are not returned to the application, for managing
+ * the operation under way. These correspond to properties in the DXPL
+ * or LAPL, and are retrieved either from the (global) cache for a
+ * default property list, or from the corresponding property in the
+ * application's (non-default) property list. Getting / setting these
+ * properties within the library does _not_ affect the application's
+ * property list. Note that the naming of these fields, <foo> and
+ * <foo>_valid, is important for the macros to work properly.
+ *
+ * - "Set" properties that are returned to the application, mainly for sending
+ * out "introspection" information ("Why did collective I/O get broken?",
+ * "Which filters are set on the chunk I just directly read in?", etc)
+ * Setting these values will cause the corresponding property in the
+ * property list to be set when the API context is popped, when
+ * returning from the API routine. Note that the naming of these fields,
+ * <foo> and <foo>_set, is important for the macros to work properly.
+ */
typedef struct H5CX_t {
/* DXPL */
hid_t dxpl_id; /* DXPL ID for API operation */
@@ -156,14 +184,14 @@ typedef struct H5CX_t {
hid_t lapl_id; /* LAPL ID for API operation */
H5P_genplist_t *lapl; /* Link Access Property List */
- /* Object tagging info */
+ /* Internal: Object tagging info */
haddr_t tag; /* Current object's tag (ohdr chunk #0 address) */
- /* Metadata cache info */
+ /* Internal: Metadata cache info */
H5AC_ring_t ring; /* Current metadata cache ring for entries */
#ifdef H5_HAVE_PARALLEL
- /* Parallel I/O settings */
+ /* Internal: Parallel I/O settings */
hbool_t coll_metadata_read; /* Whether to use collective I/O for metadata read */
MPI_Datatype btype; /* MPI datatype for buffer, when using collective I/O */
MPI_Datatype ftype; /* MPI datatype for file, when using collective I/O */
@@ -252,12 +280,23 @@ typedef struct H5CX_t {
} H5CX_t;
/* Typedef for nodes on the API context stack */
+/* Each entry into the library through an API routine invokes H5CX_push()
+ * in a FUNC_ENTER_API* macro, which pushes an H5CX_node_t on the API
+ * context [thread-local] stack, after initializing it with default values
+ * in H5CX__push_common().
+ */
typedef struct H5CX_node_t {
H5CX_t ctx; /* Context for current API call */
struct H5CX_node_t *next; /* Pointer to previous context, on stack */
} H5CX_node_t;
/* Typedef for cached default dataset transfer property list information */
+/* This is initialized to the values in the default DXPL during package
+ * initialization and then remains constant for the rest of the library's
+ * operation. When a field in H5CX_t is retrieved from an API context that
+ * uses a default DXPL, this value is copied instead of spending time looking
+ * up the property in the DXPL.
+ */
typedef struct H5CX_dxpl_cache_t {
size_t max_temp_buf; /* Maximum temporary buffer size (H5D_XFER_MAX_TEMP_BUF_NAME) */
void *tconv_buf; /* Temporary conversion buffer (H5D_XFER_TCONV_BUF_NAME) */
@@ -288,6 +327,7 @@ typedef struct H5CX_dxpl_cache_t {
} H5CX_dxpl_cache_t;
/* Typedef for cached default link access property list information */
+/* (Same as the cached DXPL struct, above, except for the default LAPL) */
typedef struct H5CX_lapl_cache_t {
size_t nlinks; /* Number of soft / UD links to traverse (H5L_ACS_NLINKS_NAME) */
} H5CX_lapl_cache_t;