diff options
author | Gerd Heber <gheber@hdfgroup.org> | 2021-04-26 19:07:29 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-26 19:07:29 (GMT) |
commit | 1d680fe04c545d601678d876ad22dea7bfc31edd (patch) | |
tree | f84a97c149df9ccf4409c5bfea04a7316c019e8a /src/H5Zpublic.h | |
parent | 12082e728de7481144db7ea3cca6f38acf0a7cac (diff) | |
download | hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.zip hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.gz hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.bz2 |
Merge doxygen2 into develop (#553)
* Fixed warnings and started H5Epublic.h.
* Include H5FD* headers to correctly resolve references.
* Doxygen2 (#330)
* H5Eauto_is_v2.
* Added a few more calls.
* Added a few more H5E calls.
* First cut of H5E v2.
* Added the deprecated v1 calls.
* Updated spacing.
* Once more.
* Taking some inspiration from Eigen3.
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.
* doxygen work. fixs format by using clang-format.
* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.
* added documentation for H5P APIs (#350)
* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios
* format corrections
* fixed grammer
* fixed herr_t
* Better name.
* A fresh look.
* add doxygen to H5Ppublic.h
* use attention instead of warning
* Add doxygen comments in H5Ppublic.h (#375)
* Add doxygen comments in H5Ppublic.h
* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops
* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt
* Fix clang-format errors
* Fix filenames in doxygen/examples
* add doxygen to H5Ppublic.h (#378)
* add doxygen to H5Ppublic.h
* use attention instead of warning
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
* Revert "add doxygen to H5Ppublic.h (#378)"
This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.
* Updated Doxygen variables.
* I forgot to copy two images.
* Enable desktop search by default.
* Add my assigned Doxygen documentation.
* Remove whitespace at EOL. Appease clang-format.
* Addressed Chris' comments.
* Added an alias for asynchronous functions.
* One space is enough for all of us.
* Slightly restructured RM page.
* address some issues
* reformatting
* Style external links.
* reformatting
* reformatting
* Added "Metadata Caching in HDF5" as a technical note example.
* Revise this soon!
* Added specification examples.
* Fixed references.
* Added H5AC cache image stuff and file format study.
* Added older FMT versions. Where did 1.0 go?
* Updated C/C++ note and replaced ambiguous labels.
* Reformat source with clang v10.0.1.
* Added the VFL technical note.
* Added what I believe might be called version 1.0 of the format.
* Added the remaining specs.
* Added H5Z callback documentation and fixed a few mistakes.
* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.
* clang-format happy?
* Ok?
* Bonus track: Deprecated H5D functions.
* Carry over the more detailed group description.
* Added documentation for the missing and deprecated H5R calls.
* Life is easier and less repetitive w/ snippets. Use them!
* Eliminate the snippet block ID artifacts in the HTML rendering.
* Fixed snippet HTML artifacts and added a few missing calls.
* Under 20 H5Ps to go!
* Almost complete!
* "This is a form of pedantry up with which I will not put." (Churchill)
* Let's not waste as much space on bulleted lists!
* First complete (?) draft of the Doxygen-based RM.
* Completeness check and minor fixes along the way.
* Pedantry.
* Adding missing H5FD calls checkpoint.
* Pedantry.
* More pedantry.
* Added H5Pset_fapl_log.
* First draft of H5ES.
* Fixed warnings.
* Prep. for map module.
* First cut of the map module.
* Pedantry.
* Possible H5F introduction.
* Fix the indentation.
* Pedantry.
* Ditto.
* Thanks to the reviewers for their comments.
* Added missing images.
* Line numbers are a distraction here.
* More examples, references, and clean-up. Don't repeat yourself!
* Clang pedantry.
* Ditto.
* More reviewer comments...
* Templatized references and cleaned up \todos.
* Committing clang-format changes
* Fixed MANIFEST.
* Addressed Quincey's comments. (OCPLs)
* Fixed a few more \todo items.
* Fixed more \todo items.
* Added attribute life cycle.
* Forgot the examples file.
* Committing clang-format changes
* Pedantry.
* Live and learn!
* Added a sample H5D life cycle.
* Committing clang-format changes
* Pedantry.
Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Zpublic.h')
-rw-r--r-- | src/H5Zpublic.h | 145 |
1 files changed, 91 insertions, 54 deletions
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 4c9b006..90277cf 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -230,16 +230,18 @@ typedef enum H5Z_EDC_t { * Return values for filter callback function */ typedef enum H5Z_cb_return_t { - H5Z_CB_ERROR = -1, - H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ - H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ - H5Z_CB_NO = 2 + H5Z_CB_ERROR = -1, /**< error value */ + H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ + H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ + H5Z_CB_NO = 2 /**< sentinel */ } H5Z_cb_return_t; +//! <!-- [H5Z_filter_func_t_snip] --> /** * Filter callback function definition */ typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); +//! <!-- [H5Z_filter_func_t_snip] --> /** * Structure for filter callback property @@ -254,58 +256,93 @@ extern "C" { #endif /** - * \details Before a dataset gets created, the \c can_apply 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). + * \brief This callback determines if a filter can be applied to the dataset + * with the characteristics provided * - * The \c can_apply 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. + * \dcpl_id + * \type_id + * \space_id * - * The \c can_apply 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. + * \return \htri_t * - * The \c can_apply callback returns positive a valid combination, - * zero for an invalid combination and negative for an error. - */ -//! [H5Z_can_apply_func_t_snip] + * \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] -/** - * \details After the "can_apply" callbacks are checked for new datasets, the - * \c set_local 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 \c set_local 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. +//! <!-- [H5Z_can_apply_func_t_snip] --> +/** + * \brief The filter operation callback function, defining a filter's operation + * on data * - * The \c set_local callback can be the NULL pointer, in which case, - * the library will assume that there are no dataset-specific settings - * for this filter. + * \dcpl_id + * \type_id + * \space_id * - * The \c set_local callback must return non-negative on success and - * negative for an error. - */ -//! [H5Z_set_local_func_t_snip] + * \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] +//! <!-- [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 @@ -321,15 +358,15 @@ typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space * output buffer. If an error occurs then the function should return * zero and leave all pointer arguments unchanged. */ -//! [H5Z_func_t_snip] +//! <!-- [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] +//! <!-- [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] +//! <!-- [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 */ @@ -340,7 +377,7 @@ typedef struct H5Z_class2_t { 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] +//! <!-- [H5Z_class2_t_snip] --> /** * \ingroup H5Z @@ -635,7 +672,7 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ -//! [H5Z_class1_t_snip] +//! <!-- [H5Z_class1_t_snip] --> typedef struct H5Z_class1_t { H5Z_filter_t id; /**< Filter ID number */ const char * name; /**< Comment for debugging */ @@ -643,7 +680,7 @@ typedef struct H5Z_class1_t { 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] +//! <!-- [H5Z_class1_t_snip] --> #endif /* H5_NO_DEPRECATED_SYMBOLS */ |