Combo set of async and other changes (#161)

* Update API tracing for new H5VL_request_status_t typedef

* Finish converting internal event set operations to use list iterator callbacks, instead of directly accessing the list structure

* Add H5VL_REQUEST_GET_ERR_STACK operation to request subclass, for retrieving a copy of the error stack for a failed asynchronous operation

* Remove 'canceled' event status from Java constants

* Be safer about releasing resources when inserting a newly opened/created object or file into an event set

* Remove H5EStest, add H5ES_WAIT_NONE for 0 timeout, and revise parameters to H5ESwait, to make it more "aggregate".

* Remove H5ES_STATUS_CANCELED from Java wrappers also

* Apply patch for dynamically registering optional VOL operations

* (a) Add async APIs for H5O module as listed in jira issue ID-283.
(b) Remove verification of name parameter in async related routines for H55A and H5L modules
    because it is checked in H5VL_setup* routine.
(c) Modify h5dump expected output due to the async changes.

* Corrections based on PR feedback.

* Further changes to make based on PR feedback.

* Remove H5Dwait & H5Fwait (moved to the async connector).  Added H5atclose
routine.  Updated 'optional op' operations.

* Fix missed merge marker, and reformatted line

* Update API tracing infrastructure for H5atclose callback

* Clean up some warnings

* Normalize against develop branch

* Correct level of indirection

* Add doxygen info for H5is_library_terminating and regression tests for it and H5atclose

* Relocate prototype (and doxygen info) for H5Aclose

* Align w/changes on develop

* Move group package initialization code to H5Gint.c, and update tracing macros

* Change non-static function declarations to be static

* Correct GCC diagnostic macro

* Ensure that H5TSpublic.h header gets installed (#129)

* Finish moving API routines that invoke VOL framework to main source files.

* Fix position of H5Fmount and H5Funmount

* Add 'wrapper' versions of async calls, to allow language wrappers and layers on top of HDF5 to pass in their application information.

* Add wrappers for dynamically registered optional operations

* Fix typo

* Update doxygen comment for H5atclose with additional detail.

* Add H5VL\*_vararg versions of H5VL routines that use va_list parameters

* Implement and test H5S_BLOCK

* Switch H5Aexists\*_async and H5Lexists\*_async to use flag to return status, instead of return value.  Make the corresponding changes through most of the v1 and v2 B-tree code.  Clean up warnings in H5public.h and cmpd_dtransform.c.

* Add H5Iregister_future routine and tests.

* Correct return value for H5Lexists_async

* Add H5_DLL macro to public H5ES API routines

* Update supported -> flags parameter for introspect_query callback

* Remove my email address.  Update passthrough VOL connector ID.

* Fix comment for post_open_api_common

* Remove unused non-blocking VOL connector

* Minor cleanup in async branch in preparation for merge to develop

* Update CMake and the Autotools to use the new pass-through VOL ID

* Finish another iteration on public H5ES routines, along with running the code reformatter

* Another round of reformatting

* Fix for SWMR daily test failures (#160)

The H5I_register_using_existing_id() call did not initialize the future
ID callbacks, causing the library to segfault when it tried to
resolve those function pointers.

* Added selective async APIs (#150)

* Added selective async APIs

Description:
    Added the following APIs:
        H5Ropen_attr_async
        H5Ropen_object_async
        H5Ropen_region_async

        H5Mcreate_async
        H5Mopen_async
        H5Mput_async
        H5Mget_async
        H5Mclose_async

        H5Tcommit_async
        H5Topen_async
        H5Tcopy_async
        H5Tclose_async
    - Updated an expected output file to include a new internal function
      in the error stack for the failure case.

* Updated async APIs per reviews, including removing async version of
H5Tcopy.

* Removed statements that were added by mistake in the previous commit.

* Fix compile issues in H5M and warnings elsewhere

* Reformat code

* Brings VOL_LIST changes from develop. (#163)

* Remove H5Dwait and H5Fwait calls, which were incorrectly brought back in

* Tiny cleanup of H5Lcreate_hard_async

* Run source formatter

* Allow for canceled operation in wait_cb

* Attempt to fix switch on string value

* Re-run source formatter

* Add H5S_BLOCK testfile to CMake clean target

* Add H5Pset_vol_async API routine and 'get_cap_flags' VOL introspection callback

* Clean up warnings

* Add H5P(set\|get)_vol_implicit_async API routines to allow \/ disallow implicit asynchronous operations (default is disallowed)

* Run formatting script

* Remove H5VL_REQUEST_WAIT\*

* Warning cleanup

* Eliminate strdup()s on statically allocated strings

* Warning cleanup

* Split H5VLrestore_lib_state into H5VLstart_lib_state and H5VLrestore_lib_state, and rename H5VLreset_lib_state to H5VLfinish_lib_state.

* Duplicate strings when building err_info to return to applicatin

* Move connector author routines into seperate header files, all included in the new hdf5dev.h header

* Run bin/trace to add TRACE macros

* Allow H5ES_NONE as a valid, but no-op, parameter to all H5ES API routines that accept an event set ID

* Clean up formatting

* Remove H5Pset/get_vol_implicit_async

* Clean up warning

* Remove H5Pget_vol_async and replace with more generic H5Pget_vol_cap_flags

* Clean up warnings

* Add H5ESfree_err_info convenience routine

* Fix typo

* Correct matching for cached VOL plugins

* Add developer header file

* Update for C99 compatibility

* Add missing trace macro

* Stop clang-format from messing with the trace macros.  Don't set up VOL wrappers for 'infrastructure' objects like requests and blobs

* Fix warning about formatting a directory

* Clean up formatting for H5E_BEGIN_TRY / H5E_END_TRY

* Reduce scope of H5ES__close

* Enable CMake checks for various types on MacOS

* Clean up properly when H5CX_retrieve_state() fails.  Also clean up many compiler warnings.

* Committing clang-format changes

* Merge from develop

* Fix mis-placed assert

* Remove commented-out code

* Re-add macro for unsetenv on Windows (I think it accidentally was merged out)

* Strengthen sanity check from error report to assertion

* Committing clang-format changes

* Add units to the comments for a few fields

* Switch 'get execution time' operation for async request tokens to be an optional operation and query if connector supports operation before retrieving it.

* Committing clang-format changes

* Remove H5ESget_time_estimate

* Committing clang-format changes

* Create developer header for datatype routines and move type conversion register/unregister routines there.

* Simplify internal H5VL_setup_name_args and H5VL_setup_idx_args routines

* Add H5VLlink_optional_op, allowing dynamicly registered optional operations for the link VOL subclass, also added H5VL_loc_params argument to the link 'optional' callback to allow them to work correctly.

* Run bin/format_source on current code

* Add H5VLobject_optional_op, allowing dynamicly registered optional operations for the object VOL subclass, also added H5VL_loc_params argument to the object 'optional' callback to allow them to work correctly.

* Run bin/format_source on current code

* Committing clang-format changes

* Revert "Switch 'get execution time' operation for async request tokens to be an optional operation and query if connector supports operation before retrieving it."

This reverts commit 5ac92014da2682bdba62d7a2524b8d90e38f6b19.

* Committing clang-format changes

* Convert attribute 'get' operation to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Update tracing macros

* Convert attribute 'specific' operation to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Convert dataset 'get' and 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Also, minor tweaks to attribute 'get' and 'specific' operation parameters.

* Convert datatype 'get' and 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Also, minor tweaks to H5O_refresh_metadata arguments.

* Reduce warnings

* Reduce warnings

* Track change to datatype 'get' callback

* Fix bug with file pointer getting invalidated when object closed

* Reformat source

* Convert file and group VOL classes 'get' and 'specific' operations to use
struct-of-tagged-union pattern for VOL callback arguments, instead of using
varargs.  Also small cleanup to the attribute get name operation.  Also moved
'mount' and 'unmount' operations to be group specific operations, instead of
file specific, to better align with their behavior (mounted files are on
groups, so a group is what is operated on).

* Remove remainder of merge conflict marking

* Convert link VOL class 'create' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Remove some unused local variables

* Convert link VOL class 'get' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Also refactor 'get name by idx' routines to return actual length of name with a parameter instead of the return value, and move some callback context structs for the link interface from the private header file into the source code module, to reduce their visibility scope.

* Update tracing macros

* Convert link VOL class 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Convert object VOL class 'get' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Convert object VOL class 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Also refactor H5G_loc_exists, et al, to return 'exists' flag in a parameter and errors with the function return value, instead of overloading both into the return value.  And, corrected logic error in test/links.c around non-existant objects in a file.

* Convert request VOL class 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.

* Convert blob VOL class 'specific' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Also removes the H5VL_BLOB_GETSIZE operation, as it's unused in the library and the blob ID size for a container is now returned with H5VL_FILE_GET_CONT_INFO.

* Add 'const' to several parameters that are only queried.

* Convert all VOL classes' 'optional' operations to use struct-of-tagged-union pattern for VOL callback arguments, instead of using varargs.  Convert several 'get' routines to return the length of an array in a parameter instead of combining it into the return value.  Move several routines to be in less public namespace.  Correct direct_chunk test to verify that parameters aren't modified on error.

* Switch get/specific/optional VOL callback argument structures to be 'async-friendly'.  Also other minor cleanups and bug-fixes.

* Add H5Pset_dataset_io_hyperslab_selection / H5S_PLIST feature, to allow skipping H5Dget_space + H5Sselect_hyperslab for async operation

* Add dynamic optional operations for request objects

* Update dynamic operation test for optional request operations

* Update a comment for an operation argument

* Run trace and format_source scripts

* Committing clang-format changes

* Committing clang-format changes

Co-authored-by: vchoi <vchoi@jelly.ad.hdfgroup.org>
Co-authored-by: vchoi-hdfgroup <55293060+vchoi-hdfgroup@users.noreply.github.com>
Co-authored-by: jhendersonHDF <jhenderson@hdfgroup.org>
Co-authored-by: Dana Robinson <derobins@hdfgroup.org>
Co-authored-by: Dana Robinson <43805+derobins@users.noreply.github.com>
Co-authored-by: bmribler <39579120+bmribler@users.noreply.github.com>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 421 insertions, 0 deletions

diff --git a/src/H5Zdevelop.h b/src/H5Zdevelop.h
new file mode 100644
index 0000000..328e221
--- /dev/null
+++ b/src/H5Zdevelop.h
@@ -0,0 +1,421 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5. The full HDF5 copyright notice, including      *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the COPYING file, which can be found at the root of the source code       *
+ * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * This file contains public declarations for the H5Z (data filter) developer
+ *      support routines.
+ */
+
+#ifndef _H5Zdevelop_H
+#define _H5Zdevelop_H
+
+/* Include package's public header */
+#include "H5Zpublic.h"
+
+/*****************/
+/* Public Macros */
+/*****************/
+
+/**
+ * Current version of the H5Z_class_t struct
+ */
+#define H5Z_CLASS_T_VERS (1)
+
+/*******************/
+/* Public Typedefs */
+/*******************/
+
+/**
+ * Structure for filter callback property
+ */
+typedef struct H5Z_cb_t {
+    H5Z_filter_func_t func;
+    void *            op_data;
+} H5Z_cb_t;
+
+/**
+ * \brief This callback determines if a filter can be applied to the dataset
+ *        with the characteristics provided
+ *
+ * \dcpl_id
+ * \type_id
+ * \space_id
+ *
+ * \return \htri_t
+ *
+ * \details Before a dataset gets created, the \ref H5Z_can_apply_func_t
+ *          callbacks for any filters used in the dataset creation property list
+ *          are called with the dataset's dataset creation property list, the
+ *          dataset's datatype and a dataspace describing a chunk (for chunked
+ *          dataset storage).
+ *
+ *          The \ref H5Z_can_apply_func_t callback must determine if the
+ *          combination of the dataset creation property list setting, the
+ *          datatype and the dataspace represent a valid combination to apply
+ *          this filter to.  For example, some cases of invalid combinations may
+ *          involve the filter not operating correctly on certain datatypes (or
+ *          certain datatype sizes), or certain sizes of the chunk dataspace.
+ *
+ *          The \ref H5Z_can_apply_func_t callback can be the NULL pointer, in
+ *          which case, the library will assume that it can apply to any
+ *          combination of dataset creation property list values, datatypes and
+ *          dataspaces.
+ *
+ *          The \ref H5Z_can_apply_func_t callback returns positive a valid
+ *          combination, zero for an invalid combination and negative for an
+ *          error.
+ */
+//! <!-- [H5Z_can_apply_func_t_snip] -->
+typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
+//! <!-- [H5Z_can_apply_func_t_snip] -->
+
+/**
+ * \brief The filter operation callback function, defining a filter's operation
+ *        on data
+ *
+ * \dcpl_id
+ * \type_id
+ * \space_id
+ *
+ * \return \herr_t
+ *
+ * \details After the \ref H5Z_can_apply_func_t callbacks are checked for new
+ *          datasets, the \ref H5Z_set_local_func_t callbacks for any filters
+ *          used in the dataset creation property list are called. These
+ *          callbacks receive the dataset's private copy of the dataset creation
+ *          property list passed in to H5Dcreate() (i.e. not the actual property
+ *          list passed in to H5Dcreate()) and the datatype ID passed in to
+ *          H5Dcreate() (which is not copied and should not be modified) and a
+ *          dataspace describing the chunk (for chunked dataset storage) (which
+ *          should also not be modified).
+ *
+ *          The \ref H5Z_set_local_func_t callback must set any parameters that
+ *          are specific to this dataset, based on the combination of the
+ *          dataset creation property list values, the datatype and the
+ *          dataspace. For example, some filters perform different actions based
+ *          on different datatypes (or datatype sizes) or different number of
+ *          dimensions or dataspace sizes.
+ *
+ *          The \ref H5Z_set_local_func_t callback can be the NULL pointer, in
+ *          which case, the library will assume that there are no
+ *          dataset-specific settings for this filter.
+ *
+ *          The \ref H5Z_set_local_func_t callback must return non-negative on
+ *          success and negative for an error.
+ */
+//! <!-- [H5Z_set_local_func_t_snip] -->
+typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
+//! <!-- [H5Z_set_local_func_t_snip] -->
+
+/**
+ * \brief The filter operation callback function, defining a filter's operation
+ *        on data
+ *
+ * \param[in] flags Bit vector specifying certain general properties of the filter
+ * \param[in] cd_nelmts Number of elements in \p cd_values
+ * \param[in] cd_values Auxiliary data for the filter
+ * \param[in] nbytes The number of valid bytes in \p buf to be filtered
+ * \param[in,out] buf_size The size of \p buf
+ * \param[in,out] buf The filter buffer
+ *
+ * \return Returns the number of valid bytes of data contained in \p buf. In the
+ *         case of failure, the return value is 0 (zero) and all pointer
+ *         arguments are left unchanged.
+ *
+ * \details A filter gets definition flags and invocation flags (defined
+ *          above), the client data array and size defined when the filter was
+ *          added to the pipeline, the size in bytes of the data on which to
+ *          operate, and pointers to a buffer and its allocated size.
+ *
+ *          The filter should store the result in the supplied buffer if
+ *          possible, otherwise it can allocate a new buffer, freeing the
+ *          original. The allocated size of the new buffer should be returned
+ *          through the \p buf_size pointer and the new buffer through the \p
+ *          buf pointer.
+ *
+ *          The return value from the filter is the number of bytes in the
+ *          output buffer. If an error occurs then the function should return
+ *          zero and leave all pointer arguments unchanged.
+ */
+//! <!-- [H5Z_func_t_snip] -->
+typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
+                             size_t nbytes, size_t *buf_size, void **buf);
+//! <!-- [H5Z_func_t_snip] -->
+
+/**
+ * The filter table maps filter identification numbers to structs that
+ * contain a pointers to the filter function and timing statistics.
+ */
+//! <!-- [H5Z_class2_t_snip] -->
+typedef struct H5Z_class2_t {
+    int                  version;         /**< Version number of the H5Z_class_t struct     */
+    H5Z_filter_t         id;              /**< Filter ID number                             */
+    unsigned             encoder_present; /**< Does this filter have an encoder?            */
+    unsigned             decoder_present; /**< Does this filter have a decoder?             */
+    const char *         name;            /**< Comment for debugging                        */
+    H5Z_can_apply_func_t can_apply;       /**< The "can apply" callback for a filter        */
+    H5Z_set_local_func_t set_local;       /**< The "set local" callback for a filter        */
+    H5Z_func_t           filter;          /**< The actual filter function                   */
+} H5Z_class2_t;
+//! <!-- [H5Z_class2_t_snip] -->
+
+/********************/
+/* Public Variables */
+/********************/
+
+/*********************/
+/* Public Prototypes */
+/*********************/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \ingroup H5Z
+ *
+ * \brief Registers a new filter with the HDF5 library
+ *
+ * \param[in] cls A pointer to a buffer for the struct containing the
+ *                filter-definition
+ *
+ * \return \herr_t
+ *
+ * \details H5Zregister() registers a new filter with the HDF5 library.
+ *
+ * \details Making a new filter available to an application is a two-step
+ *          process. The first step is to write the three filter callback
+ *          functions described below: \c can_apply, \c set_local, and \c
+ *          filter. This call to H5Zregister(), registering the filter with the
+ *          library, is the second step. The can_apply and set_local fields can
+ *          be set to NULL if they are not required for the filter being
+ *          registered.
+ *
+ *          H5Zregister() accepts a single parameter, a pointer to a buffer for
+ *          the \p cls data structure. That data structure must conform to one
+ *          of the following definitions:
+ *          \snippet this H5Z_class1_t_snip
+ *          or
+ *          \snippet this H5Z_class2_t_snip
+ *
+ *          \c version is a library-defined value reporting the version number
+ *          of the #H5Z_class_t struct. This currently must be set to
+ *          #H5Z_CLASS_T_VERS.
+ *
+ *          \c id is the identifier for the new filter. This is a user-defined
+ *          value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These
+ *          values are defined in the HDF5 source file H5Zpublic.h, but the
+ *          symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be
+ *          used instead of the literal values.
+ *
+ *          \c encoder_present is a library-defined value indicating whether
+ *          the filter’s encoding capability is available to the application.
+ *
+ *          \c decoder_present is a library-defined value indicating whether
+ *          the filter’s encoding capability is available to the application.
+ *
+ *          \c name is a descriptive comment used for debugging, may contain a
+ *          descriptive name for the filter, and may be the null pointer.
+ *
+ *          \c can_apply, described in detail below, is a user-defined callback
+ *          function which determines whether the combination of the dataset
+ *          creation property list values, the datatype, and the dataspace
+ *          represent a valid combination to apply this filter to.
+ *
+ *          \c set_local, described in detail below, is a user-defined callback
+ *          function which sets any parameters that are specific to this
+ *          dataset, based on the combination of the dataset creation property
+ *          list values, the datatype, and the dataspace.
+ *
+ *          \c filter, described in detail below, is a user-defined callback
+ *          function which performs the action of the filter.
+ *
+ *          The statistics associated with a filter are not reset by this
+ *          function; they accumulate over the life of the library.
+ *
+ *          #H5Z_class_t is a macro which maps to either H5Z_class1_t or
+ *          H5Z_class2_t, depending on the needs of the application. To affect
+ *          only this macro, H5Z_class_t_vers may be defined to either 1 or 2.
+ *          Otherwise, it will behave in the same manner as other API
+ *          compatibility macros. See API Compatibility Macros in HDF5 for more
+ *          information. H5Z_class1_t matches the #H5Z_class_t structure that is
+ *          used in the 1.6.x versions of the HDF5 library.
+ *
+ *          H5Zregister() will automatically detect which structure type has
+ *          been passed in, regardless of the mapping of the #H5Z_class_t macro.
+ *          However, the application must make sure that the fields are filled
+ *          in according to the correct structure definition if the macro is
+ *          used to declare the structure.
+ *
+ *          \Bold{The callback functions:}\n Before H5Zregister() can link a
+ *          filter into an application, three callback functions must be
+ *          defined as described in the HDF5 library header file H5Zpublic.h.
+ *
+ *          When a filter is applied to the fractal heap for a group (e.g.,
+ *          when compressing group metadata) and if the can apply and set local
+ *          callback functions have been defined for that filter, HDF5 passes
+ *          the value -1 for all parameters for those callback functions. This
+ *          is done to ensure that the filter will not be applied to groups if
+ *          it relies on these parameters, as they are not applicable to group
+ *          fractal heaps; to operate on group fractal heaps, a filter must be
+ *          capable of operating on an opaque block of binary data.
+ *
+ *          The \Emph{can apply} callback function must return a positive value
+ *          for a valid combination, zero for an invalid combination, and a
+ *          negative value for an error.
+ *          \snippet this H5Z_can_apply_func_t_snip
+ *
+ *          Before a dataset is created, the \Emph{can apply} callbacks for any
+ *          filters used in the dataset creation property list are called with
+ *          the dataset's dataset creation property list, \c dcpl_id, the
+ *          dataset's datatype, \p type_id, and a dataspace describing a chunk,
+ *          \p space_id, (for chunked dataset storage).
+ *
+ *          This callback must determine whether the combination of the dataset
+ *          creation property list settings, the datatype, and the dataspace
+ *          represent a valid combination to which to apply this filter. For
+ *          example, an invalid combination may involve the filter not
+ *          operating correctly on certain datatypes, on certain datatype
+ *          sizes, or on certain sizes of the chunk dataspace. If this filter
+ *          is enabled through H5Pset_filter() as optional and the can apply
+ *          function returns 0, the library will skip the filter in the filter
+ *          pipeline.
+ *
+ *          This callback can be the NULL pointer, in which case the library
+ *          will assume that the filter can be applied to a dataset with any
+ *          combination of dataset creation property list values, datatypes,
+ *          and dataspaces.
+ *
+ *          The \Emph{set local} callback function is defined as follows:
+ *          \snippet this H5Z_set_local_func_t_snip
+ *
+ *          After the can apply callbacks are checked for a new dataset, the
+ *          \Emph{set local} callback functions for any filters used in the
+ *          dataset creation property list are called. These callbacks receive
+ *          \c dcpl_id, the dataset's private copy of the dataset creation
+ *          property list passed in to H5Dcreate() (i.e. not the actual
+ *          property list passed in to H5Dcreate()); \c type_id, the datatype
+ *          identifier passed in to H5Dcreate(), which is not copied and should
+ *          not be modified; and \c space_id, a dataspace describing the chunk
+ *          (for chunked dataset storage), which should also not be modified.
+ *
+ *          The set local callback must set any filter parameters that are
+ *          specific to this dataset, based on the combination of the dataset
+ *          creation property list values, the datatype, and the dataspace. For
+ *          example, some filters perform different actions based on different
+ *          datatypes, datatype sizes, numbers of dimensions, or dataspace
+ *          sizes.
+ *
+ *          The \Emph{set local} callback may be the NULL pointer, in which
+ *          case, the library will assume that there are no dataset-specific
+ *          settings for this filter.
+ *
+ *          The \Emph{set local} callback function must return a non-negative
+ *          value on success and a negative value for an error.
+ *
+ *          The \Emph{filter operation} callback function, defining the
+ *          filter's operation on the data, is defined as follows:
+ *          \snippet this H5Z_func_t_snip
+ *
+ *          The parameters \c flags, \c cd_nelmts, and \c cd_values are the
+ *          same as for the function H5Pset_filter(). The one exception is that
+ *          an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is
+ *          called as part of the input pipeline.
+ *
+ *          The parameter \c buf points to the input buffer which has a size of
+ *          \c buf_size bytes, \c nbytes of which are valid data.
+ *
+ *          The filter should perform the transformation in place if possible.
+ *          If the transformation cannot be done in place, then the filter
+ *          should allocate a new buffer with malloc() and assign it to \c buf,
+ *          assigning the allocated size of that buffer to \c buf_size. The old
+ *          buffer should be freed by calling free().
+ *
+ *          If successful, the \Emph{filter operation} callback function
+ *          returns the number of valid bytes of data contained in \c buf. In
+ *          the case of failure, the return value is 0 (zero) and all pointer
+ *          arguments are left unchanged.
+ *
+ * \version 1.8.6 Return type for the \Emph{can apply} callback function,
+ *                \ref H5Z_can_apply_func_t, changed to \ref htri_t.
+ * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local}
+ *                callback functions changed to accommodate the use of filters
+ *                with group fractal heaps.
+ * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure
+ *                introduced for backwards compatibility with release 1.6.x,
+ *                and #H5Z_class_t macro introduced in this release. Function
+ *                modified to accept either structure type.
+ * \version 1.8.0 The fields \c version, \c encoder_present, and
+ *                \c decoder_present were added to the #H5Z_class_t \c struct
+ *                in this release.
+ * \version 1.6.0 This function was substantially revised in Release 1.6.0 with
+ *                a new #H5Z_class_t struct and new set local and can apply
+ *                callback functions.
+ *
+ */
+H5_DLL herr_t H5Zregister(const void *cls);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Unregisters a filter.
+ *
+ * \param[in] id Identifier of the filter to be unregistered.
+ * \return \herr_t
+ *
+ * \details H5Zunregister() unregisters the filter specified in \p id.
+ *
+ * \details This function first iterates through all opened datasets and
+ *          groups. If an open object that uses this filter is found, the
+ *          function will fail with a message indicating that an object using
+ *          the filter is still open. All open files are then flushed to make
+ *          sure that all cached data that may use this filter are written out.
+ *
+ *          If the application is a parallel program, all processes that
+ *          participate in collective data write should call this function to
+ *          ensure that all data is flushed.
+ *
+ *          After a call to H5Zunregister(), the filter specified in filter
+ *          will no longer be available to the application.
+ *
+ * \version 1.8.12 Function modified to check for open objects using the
+ *                 filter.
+ * \since 1.6.0
+ */
+H5_DLL herr_t H5Zunregister(H5Z_filter_t id);
+
+#ifdef __cplusplus
+}
+#endif
+
+/* Symbols defined for compatibility with previous versions of the HDF5 API.
+ *
+ * Use of these symbols is deprecated.
+ */
+#ifndef H5_NO_DEPRECATED_SYMBOLS
+
+/**
+ * The filter table maps filter identification numbers to structs that
+ * contain a pointers to the filter function and timing statistics.
+ */
+//! <!-- [H5Z_class1_t_snip] -->
+typedef struct H5Z_class1_t {
+    H5Z_filter_t         id;        /**< Filter ID number			     */
+    const char *         name;      /**< Comment for debugging		     */
+    H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */
+    H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */
+    H5Z_func_t           filter;    /**< The actual filter function		     */
+} H5Z_class1_t;
+//! <!-- [H5Z_class1_t_snip] -->
+
+#endif /* H5_NO_DEPRECATED_SYMBOLS */
+
+#endif /* _H5Zdevelop_H */