summaryrefslogtreecommitdiffstats
path: root/hl/src/H5DOpublic.h
diff options
context:
space:
mode:
Diffstat (limited to 'hl/src/H5DOpublic.h')
-rw-r--r--hl/src/H5DOpublic.h199
1 files changed, 199 insertions, 0 deletions
diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h
index 88616a3..99358b3 100644
--- a/hl/src/H5DOpublic.h
+++ b/hl/src/H5DOpublic.h
@@ -18,6 +18,29 @@
extern "C" {
#endif
+/**\defgroup H5DO Optimizations
+ *
+ * <em>Bypassing default HDF5 behavior in order to optimize for specific
+ * use cases (H5DO)</em>
+ *
+ * HDF5 functions described is this section are implemented in the HDF5 High-level
+ * library as optimized functions. These functions generally require careful setup
+ * and testing as they enable an application to bypass portions of the HDF5
+ * library’s I/O pipeline for performance purposes.
+ *
+ * These functions are distributed in the standard HDF5 distribution and are
+ * available any time the HDF5 High-level library is available.
+ *
+ * - \ref H5DOappend
+ * \n Appends data to a dataset along a specified dimension.
+ * - \ref H5DOread_chunk
+ * \n Reads a raw data chunk directly from a dataset in a file into a buffer (DEPRECATED)
+ * - \ref H5DOwrite_chunk
+ * \n Writes a raw data chunk from a buffer directly to a dataset in a file (DEPRECATED)
+ * .
+ *
+ */
+
/*-------------------------------------------------------------------------
*
* "Optimized dataset" routines.
@@ -25,6 +48,48 @@ extern "C" {
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Appends data to a dataset along a specified dimension.
+ *
+ * \param[in] dset_id Dataset identifier
+ * \param[in] dxpl_id Dataset transfer property list identifier
+ * \param[in] axis Dataset Dimension (0-based) for the append
+ * \param[in] extension Number of elements to append for the
+ * axis-th dimension
+ * \param[in] memtype The memory datatype identifier
+ * \param[in] buf Buffer with data for the append
+ *
+ * \return \herr_t
+ *
+ * \details The H5DOappend() routine extends a dataset by \p extension
+ * number of elements along a dimension specified by a
+ * dimension \p axis and writes \p buf of elements to the
+ * dataset. Dimension \p axis is 0-based. Elements’ type
+ * is described by \p memtype.
+ *
+ * This routine combines calling H5Dset_extent(),
+ * H5Sselect_hyperslab(), and H5Dwrite() into a single routine
+ * that simplifies application development for the common case
+ * of appending elements to an existing dataset.
+ *
+ * For a multi-dimensional dataset, appending to one dimension
+ * will write a contiguous hyperslab over the other dimensions.
+ * For example, if a 3-D dataset has dimension sizes (3, 5, 8),
+ * extending the 0th dimension (currently of size 3) by 3 will
+ * append 3*5*8 = 120 elements (which must be pointed to by the
+ * \p buffer parameter) to the dataset, making its final
+ * dimension sizes (6, 5, 8).
+ *
+ * If a dataset has more than one unlimited dimension, any of
+ * those dimensions may be appended to, although only along
+ * one dimension per call to H5DOappend().
+ *
+ * \since 1.10.0
+ *
+ */
H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype,
const void *buf);
@@ -35,8 +100,142 @@ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t e
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Compatibility wrappers for functionality moved to H5D */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Writes a raw data chunk from a buffer directly to a dataset in a file.
+ *
+ * \param[in] dset_id Identifier for the dataset to write to
+ * \param[in] dxpl_id Transfer property list identifier for
+ * this I/O operation
+ * \param[in] filters Mask for identifying the filters in use
+ * \param[in] offset Logical position of the chunk’s first element
+ * in the dataspace
+ * \param[in] data_size Size of the actual data to be written in bytes
+ * \param[in] buf Buffer containing data to be written to the chunk
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function was deprecated in favor of the function
+ * H5Dwrite_chunk() of HDF5-1.10.3.
+ * The functionality of H5DOwrite_chunk() was moved
+ * to H5Dwrite_chunk().
+ * \deprecated For compatibility, this API call has been left as a stub which
+ * simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk().
+ *
+ * \details The H5DOwrite_chunk() writes a raw data chunk as specified by its
+ * logical \p offset in a chunked dataset \p dset_id from the application
+ * memory buffer \p buf to the dataset in the file. Typically, the data
+ * in \p buf is preprocessed in memory by a custom transformation, such as
+ * compression. The chunk will bypass the library’s internal data
+ * transfer pipeline, including filters, and will be written directly to the file.
+ *
+ * \p dxpl_id is a data transfer property list identifier.
+ *
+ * \p filters is a mask providing a record of which filters are used
+ * with the chunk. The default value of the mask is zero (\c 0),
+ * indicating that all enabled filters are applied. A filter is skipped
+ * if the bit corresponding to the filter’s position in the pipeline
+ * (<tt>0 ≤ position < 32</tt>) is turned on. This mask is saved
+ * with the chunk in the file.
+ *
+ * \p offset is an array specifying the logical position of the first
+ * element of the chunk in the dataset’s dataspace. The length of the
+ * offset array must equal the number of dimensions, or rank, of the
+ * dataspace. The values in \p offset must not exceed the dimension limits
+ * and must specify a point that falls on a dataset chunk boundary.
+ *
+ * \p data_size is the size in bytes of the chunk, representing the number of
+ * bytes to be read from the buffer \p buf. If the data chunk has been
+ * precompressed, \p data_size should be the size of the compressed data.
+ *
+ * \p buf is the memory buffer containing data to be written to the chunk in the file.
+ *
+ * \attention Exercise caution when using H5DOread_chunk() and H5DOwrite_chunk(),
+ * as they read and write data chunks directly in a file.
+ * H5DOwrite_chunk() bypasses hyperslab selection, the conversion of data
+ * from one datatype to another, and the filter pipeline to write the chunk.
+ * Developers should have experience with these processes before
+ * using this function. Please see
+ * <a href="https://portal.hdfgroup.org/display/HDF5/Using+the+Direct+Chunk+Write+Function">
+ * Using the Direct Chunk Write Function</a>
+ * for more information.
+ *
+ * \note H5DOread_chunk() and H5DOwrite_chunk() are not
+ * supported under parallel and do not support variable length types.
+ *
+ * \par Example
+ * The following code illustrates the use of H5DOwrite_chunk to write
+ * an entire dataset, chunk by chunk:
+ * \snippet H5DO_examples.c H5DOwrite
+ *
+ * \version 1.10.3 Function deprecated in favor of H5Dwrite_chunk.
+ *
+ * \since 1.8.11
+ */
H5_HLDLL herr_t H5DOwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset,
size_t data_size, const void *buf);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Reads a raw data chunk directly from a dataset in a file into a buffer.
+ *
+ * \param[in] dset_id Identifier for the dataset to be read
+ * \param[in] dxpl_id Transfer property list identifier for
+ * this I/O operation
+ * \param[in] offset Logical position of the chunk’s first
+ element in the dataspace
+ * \param[in,out] filters Mask for identifying the filters used
+ * with the chunk
+ * \param[in] buf Buffer containing the chunk read from
+ * the dataset
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function was deprecated in favor of the function
+ * H5Dread_chunk() as of HDF5-1.10.3.
+ * In HDF5 1.10.3, the functionality of H5DOread_chunk()
+ * was moved to H5Dread_chunk().
+ * \deprecated For compatibility, this API call has been left as a stub which
+ * simply calls H5Dread_chunk(). New code should use H5Dread_chunk().
+ *
+ * \details The H5DOread_chunk() reads a raw data chunk as specified
+ * by its logical \p offset in a chunked dataset \p dset_id
+ * from the dataset in the file into the application memory
+ * buffer \p buf. The data in \p buf is read directly from the file
+ * bypassing the library’s internal data transfer pipeline,
+ * including filters.
+ *
+ * \p dxpl_id is a data transfer property list identifier.
+ *
+ * The mask \p filters indicates which filters are used with the
+ * chunk when written. A zero value indicates that all enabled filters
+ * are applied on the chunk. A filter is skipped if the bit corresponding
+ * to the filter’s position in the pipeline
+ * (<tt>0 ≤ position < 32</tt>) is turned on.
+ *
+ * \p offset is an array specifying the logical position of the first
+ * element of the chunk in the dataset’s dataspace. The length of the
+ * offset array must equal the number of dimensions, or rank, of the
+ * dataspace. The values in \p offset must not exceed the dimension
+ * limits and must specify a point that falls on a dataset chunk boundary.
+ *
+ * \p buf is the memory buffer containing the chunk read from the dataset
+ * in the file.
+ *
+ * \par Example
+ * The following code illustrates the use of H5DOread_chunk()
+ * to read a chunk from a dataset:
+ * \snippet H5DO_examples.c H5DOread
+ *
+ * \version 1.10.3 Function deprecated in favor of H5Dread_chunk.
+ *
+ * \since 1.10.2, 1.8.19
+ */
H5_HLDLL herr_t H5DOread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters /*out*/,
void *buf /*out*/);