![]() |
HDF5
1.15.0.ac650fa
API Reference
|
Bypassing default HDF5 behavior in order to optimize for specific use cases (H5DO)
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.
Functions | |
H5_HLDLL herr_t | H5DOappend (hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype, const void *buf) |
Appends data to a dataset along a specified dimension. More... | |
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) |
Writes a raw data chunk from a buffer directly to a dataset in a file. More... | |
H5_HLDLL herr_t | H5DOread_chunk (hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters, void *buf) |
Reads a raw data chunk directly from a dataset in a file into a buffer. More... | |
H5_HLDLL herr_t H5DOappend | ( | hid_t | dset_id, |
hid_t | dxpl_id, | ||
unsigned | axis, | ||
size_t | extension, | ||
hid_t | memtype, | ||
const void * | buf | ||
) |
Appends data to a dataset along a specified dimension.
[in] | dset_id | Dataset identifier |
[in] | dxpl_id | Dataset transfer property list identifier |
[in] | axis | Dataset Dimension (0-based) for the append |
[in] | extension | Number of elements to append for the axis-th dimension |
[in] | memtype | The memory datatype identifier |
[in] | buf | Buffer with data for the append |
The H5DOappend() routine extends a dataset by extension
number of elements along a dimension specified by a dimension axis
and writes buf
of elements to the dataset. Dimension axis
is 0-based. Elements’ type is described by 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 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().
H5_HLDLL herr_t H5DOread_chunk | ( | hid_t | dset_id, |
hid_t | dxpl_id, | ||
const hsize_t * | offset, | ||
uint32_t * | filters, | ||
void * | buf | ||
) |
Reads a raw data chunk directly from a dataset in a file into a buffer.
[in] | dset_id | Identifier for the dataset to be read |
[in] | dxpl_id | Transfer property list identifier for this I/O operation |
[in] | offset | Logical position of the chunk's first element in the dataspace |
[in,out] | filters | Mask for identifying the filters used with the chunk |
[in] | buf | Buffer containing the chunk read from the dataset |
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().
For compatibility, this API call has been left as a stub which simply calls H5Dread_chunk(). New code should use H5Dread_chunk().
The H5DOread_chunk() reads a raw data chunk as specified by its logical offset
in a chunked dataset dset_id
from the dataset in the file into the application memory buffer buf
. The data in buf
is read directly from the file bypassing the library's internal data transfer pipeline, including filters.
dxpl_id
is a data transfer property list identifier.
The mask 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 (0 ≤ position < 32
) is turned on.
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 offset
must not exceed the dimension limits and must specify a point that falls on a dataset chunk boundary.
buf
is the memory buffer containing the chunk read from the dataset in the file.
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 | ||
) |
Writes a raw data chunk from a buffer directly to a dataset in a file.
[in] | dset_id | Identifier for the dataset to write to |
[in] | dxpl_id | Transfer property list identifier for this I/O operation |
[in] | filters | Mask for identifying the filters in use |
[in] | offset | Logical position of the chunk's first element in the dataspace |
[in] | data_size | Size of the actual data to be written in bytes |
[in] | buf | Buffer containing data to be written to the chunk |
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().
For compatibility, this API call has been left as a stub which simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk().
The H5DOwrite_chunk() writes a raw data chunk as specified by its logical offset
in a chunked dataset dset_id
from the application memory buffer buf
to the dataset in the file. Typically, the data in 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.
dxpl_id
is a data transfer property list identifier.
filters
is a mask providing a record of which filters are used with the chunk. The default value of the mask is zero (0
), indicating that all enabled filters are applied. A filter is skipped if the bit corresponding to the filter's position in the pipeline (0 ≤ position < 32
) is turned on. This mask is saved with the chunk in the file.
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 offset
must not exceed the dimension limits and must specify a point that falls on a dataset chunk boundary.
data_size
is the size in bytes of the chunk, representing the number of bytes to be read from the buffer buf
. If the data chunk has been precompressed, data_size
should be the size of the compressed data.
buf
is the memory buffer containing data to be written to the chunk in the file.