From 62e5602e7f72b6baa9fd79f5086e0cfae6b14327 Mon Sep 17 00:00:00 2001 From: Matthew Larson Date: Tue, 11 Jun 2024 11:52:39 -0500 Subject: [PATCH] Document 'return-and-read' field in API context --- src/H5CX.c | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/src/H5CX.c b/src/H5CX.c index f23c90486e3..be31f232bda 100644 --- a/src/H5CX.c +++ b/src/H5CX.c @@ -156,10 +156,10 @@ * 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, and - * _valid, is important for the H5CX_RETRIEVE_PROP_VALID ahd - * H5CX_RETRIEVE_PROP_VALID_SET macros to work properly. + * _valid, is important for the H5CX_RETRIEVE_PROP_VALID + * macro to work properly. * - * - "Return-only"" properties that are returned to the application, mainly + * - "Return-only" properties that are returned to the application, mainly * for sending out "introspection" information ("Why did collective I/O * get broken for this operation?", "Which filters are set on the chunk I * just directly read in?", etc) Setting these fields will cause the @@ -167,6 +167,19 @@ * context is popped, when returning from the API routine. Note that the * naming of these fields, and _set, is important for the * H5CX_TEST_SET_PROP and H5CX_SET_PROP macros to work properly. + * + * - "Return-and-read" properties that are returned to the application to send out introspection information, + * but are also queried by the library internally. Internal queries always retrieve the original value + * from the property list, and update the context's value to match. These properties have both a 'valid' + * and 'set' flag. _valid is true if the field has ever been populated from its underlying property + * list. _set flag is true if this field has ever been set on the context for application + * introspection. The naming of these fields is important for the H5CX_RETRIEVE_PROP_VALID_SET macro to + * work properly. + * + * Note that if a set operation is followed by an internal read, it is possible for _set to be true + * while the value in the context matches the underlying property list, resulting in a redundant write to + * the property list when the context is popped. Similarly, if a field has been set on the context but + * never read internally, _valid will be false despite the context containing a meaningful value. */ typedef struct H5CX_t { /* DXPL */ @@ -1082,7 +1095,7 @@ H5CX_restore_state(const H5CX_state_t *api_state) /*------------------------------------------------------------------------- * Function: H5CX_free_state * - * Purpose: Free a previously retrievedAPI context state + * Purpose: Free a previously retrieved API context state * * Return: Non-negative on success / Negative on failure *