Document VOL object wrapping context #4611
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mattjala
added
Merge - To 1.14
Priority - 2. Medium ⏹
mattjala
requested review from
lrknox,
derobins,
byrnHDF,
fortnern,
jhendersonHDF,
qkoziol,
vchoi-hdfgroup,
bmribler,
glennsong09 and
brtnfld
as code owners
mattjala
force-pushed
the
h5vl_ctx_wrap_docs
branch
from
565a6d9 to
9c9e9d4
Compare
mattjala
force-pushed
the
h5vl_ctx_wrap_docs
branch
from
9c9e9d4 to
ca7ec04
Compare
byrnHDF
approved these changes
Jun 27, 2024
| \endcode | ||
| </td> | ||
| </tr> | ||
| </table> | ||
|
|
||
| \subsubsection subsubsecVOLRefWrapctx wrap: get_wrap_ctx | ||
| Get a VOL connector's object wrapping context. | ||
|
|
||
| The context should be returned in dynamically allocated memory under <em>*wrap_ctx</em>. |
There was a problem hiding this comment.
@qkoziol When trying to help with documenting the VOL wrap class, I couldn't quite figure out what the wrap context object was necessary for. Do you happen to remember why a passthrough VOL needs to return a wrapping context object for the library to keep around?
There was a problem hiding this comment.
The wrapping context object is saved on the API Context, which is where H5VL__wrap_obj retrieves it from to provide it to the wrap object callback
There was a problem hiding this comment.
Wrapping objects is necessary for the library to return objects from user callbacks and other scenarios where the library has an object from a terminal VOL connector and needs to eventually pass back an ID to an application. The library has to wrap the terminal object using pass-throughs 'wrap' callbacks, so that the resulting ID refers to an object that can later be unwrapped by the connector stack and reach the terminal connector again.
There was a problem hiding this comment.
Right, I was asking more about the wrapping context object in particular and why a connector needs to allocate one and pass it back to the library.
There was a problem hiding this comment.
The wrapping context is what the library gives back to a VOL connector to say "wrap this object for me". Without the wrapping context, the pass-through connector wouldn't know which connector stack it was supposed to be wrapping an object for.
qkoziol
approved these changes
Jun 28, 2024
derobins
approved these changes
Jun 29, 2024
qkoziol
pushed a commit
to qkoziol/hdf5
that referenced
this pull request
Jul 2, 2024
lrknox
pushed a commit
to lrknox/hdf5
that referenced
this pull request
Jul 2, 2024
lrknox
added a commit
that referenced
this pull request
Jul 3, 2024
* Fix typos in context/property documentation (#4550) * Fix CI markdown link check http 500 errors (#4556) Sites like GitLab can have internal problems that return http 500 errors while they fix their problems. Some sites also return http 200 OK, which is fine. This PR adds a config file to the markdown link check so those are considered "passing" and don't break the CI. * Simplify property copying between lists internally (#4551) * Add Python examples (#4546) These examples are referred to from the replacement page of https://portal.hdfgroup.org/display/HDF5/Other+Examples. * Correct property cb signatures in docs (#4554) * Correct property cb signatures in docs * Correct delete callback type name in docs * add missing word to H5P__free_prop doc * Move C++ and Fortran and examples to HDF5Examples folder (#4552) * Document 'return-and-read' field in API context (#4560) * Add compression includes to tests needing zlib support (#4561) * Allow usage of page buffering for serial file access from parallel HDF5 builds (#4568) * Remove old version of libaec (#4567) * Add property names to context field docs (#4563) * Document property shared name behavior (#4565) * Clarify H5CX macro documentation (#4569) * Document H5Punregister modifying default properties (#4570) * Update NVHPC to 24.5 (#4171) We don't test parallel in other GitHub actions, so this also converts the NVHPC check to configure and build only while we discuss how we'll test parallel HDF5 in GitHub. There is a blocking GitHub issue to address the test failures for HDF5 1.14.5 (#4571). * Clean up comments in H5FDros3.c (#4572) * Rename INSTALL_Auto.txt to INSTALL_Autotools.txt (#4575) * Clean up ros3 VFD stats code (#4579) * Removes printf debugging * Simplifies and centralizes stats code * Use #ifdef ROS3_STATS instead of #if * Other misc tidying * Turn off ros3 VFD stat collection by default (#4581) Not a new change - an artifact from a previous check-in. * Pause recording errors instead of clearing the error stack (#4475) An internal capability that's similar to the H5E_BEGIN_TRY / H5E_END_TRY macros in H5Epublic.h, but more efficient since we can avoid pushing errors on the stack entirely (and those macros use public API routines). This capability (and other techniques) can be used to remove use of H5E_clear_stack() and H5E_BEGIN_TRY / H5E_END_TRY within library routines. We want to remove H5E_clear_stack() because it can trigger calls to the H5I interface from within the H5E code, which creates a great deal of complexity for threadsafe code. And we want to remove H5E_BEGIN_TRY / H5E_END_TRY's because they make public API calls from within the library code. Also some other minor tidying in routines related to removing the use of H5E_clear_stack() and H5E_BEGIN_TRY / H5E_END_TRY from H5Fint.c * Add page buffer cache command line option to tools (#4562) Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> * Clarify documentation for H5CX_get_data_transform (#4580) * Correct comment for H5CX_get_data_transform * Document why data transform ctx field doesnt use macro * Remove public API call from ros3 VFD (#4583) * Remove printf debugging from H5FDs3comms.c (#4584) * Cleanup of ros3 test (#4587) * Removed JS* macro scheme (replaced w/ h5test.h macros) * Moved curl setup/teardown to main() * A lot of cleanup and simplification * Removed unused code from H5FDs3comms.c (#4588) * H5FD_s3comms_nlowercase() * H5FD_s3comms_trim() * H5FD_s3comms_uriencode() * Remove magic fields from s3comms structs (#4589) * Remove dead H5FD_s3comms_percent_encode_char() (#4591) * Rework the TestExpress usage and refactor dead code (#4590) * Skip examples if running sanitizers (#4592) * Clean up s3comms test code (#4594) * Remove JS* macros * Remove dead code * Bring in line with other test code * Add publish to bucket workflow (#4566) * Update abi report CI workflow for last release (#4596) * Update abi report workflow to handle 1.14.4.3 release * Update name of java report * Document that ctx VOL property isn't drawn from the FAPL (#4597) * Update macos workflow to 14 (keep 13 as alternate) (#4603) * Removed unnecessary call to H5E_clear_stack (#4607) H5FO_opened and H5SL_search don't push errors on the stack * Bring subfiling VFD code closer to typical library code (#4595) Remove API calls, use FUNC_ENTER/LEAVE macros, use the library's error macros, rename functions to have more standardized names, etc. * Correct documentation for return-and-read fields (#4598) * These two generators create strings without NUL for testing (#4608) * Fix Fortran pkconfig to indicate full path of modules (#4593) * Updated release schedule (#4615) 1.16 and 2.0 information * Document VOL object wrapping context (#4611) * Earray.c and farray.c in hdf5_1_14 still need time_t curr_time for HDsrandom. * Remove line to use future 116_API from CMakeListat.txt files in HDF5 examples directories
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 5, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 6, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 6, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 9, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 10, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 17, 2024
mattjala
added a commit
to mattjala/hdf5
that referenced
this pull request
Dec 19, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The VOL object wrapping context is documented very sparsely at the moment. This PR adds an overview of what it's for and when it's used, and details what the
wrap_clscallbacks should do in the VOL connector author guide.