herr_t H5Pset_append_flush (
hid_t dapl_id,
int ndims,
const hsize_t boundary[],
H5D_append_cb_t func,
void *user_data
)H5Pset_append_flush sets the following two actions to
perform for a dataset associated with the dataset access property
list dapl_id:
func set in the
property list
When a user is appending data to a dataset via H5DOappend
and the dataset’s newly extended dimension size hits a specified
boundary, the library will first perform action #1 listed above.
Upon return from the callback function, the library will then perform
the above action #2 and return to the user. If no boundary is hit
or set, the two actions above are not invoked.
The specified boundary is indicated by the parameter
boundary.
It is a 1-dimensional array with ndims elements,
which should be the same as the rank of the dataset’s dataspace.
While appending to a dataset along a particular dimension index via
H5DOappend, the library determines a boundary is reached
when the resulting dimension size is divisible by
boundary[index].
A zero value for boundary[index] indicates no
boundary is set for that dimension index.
The setting of this property will apply only for a chunked dataset with an extendible dataspace. A dataspace is extendible when it is defined with either one of the following:
When creating or opening a chunked dataset, the library will check whether the boundary as specified in the access property list is set up properly. The library will fail the dataset create or open if the following conditions are true:
ndims, the number of elements for
boundary, is not the same as the rank of the
dataset’s dataspace.
The callback function func must conform to the
following prototype:
typedef herr_t (H5D_append_cb_t)(hid_t
dataset_id, hsize_t *cur_dims, void
*user_data)
The parameters of the callback function, per the above prototype, are defined as follows:
dataset_id is the dataset identifier.cur_dims is the dataset’s current
dimension sizes when a boundary is hit.user_data is the user-defined input data.hid_t dapl_id |
IN: Dataset access property list identifier. |
int ndims |
IN: The number of elements for boundary. |
hsize_t *boundary |
IN: The dimension sizes used to determine the boundary. |
H5D_append_cb_t func |
IN: The user-defined callback function. |
void *user_data |
IN: The user-defined input data. |
H5DOappend.
hsize_t dims[2] = {0, 100};
hsize_t max_dims[2] = {H5S_UNLIMITED, 100};
hsize_t boundary_dims[2] = {5, 0};
unsigned counter;
void *buf;
hid_t file_id;
hid_t dataset_id, dapl_id, type;
/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR|H5F_ACC_SWMR_WRITE, H5P_DEFAULT);
/* Create a copy of the dataset access property list */
dapl_id = H5Pcreate(H5P_DATASET_ACCESS);
/* Set up the append property values */
/* boundary_dims[0]=5: to invoke callback and flush every 5 lines */
/* boundary_dims[1]=0: no boundary is set for the non-extendible dimension */
/* append_cb: callback function to invoke when hitting boundary (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_append_flush(dapl_id, 2, boundary_dims, append_cb, &counter);
/* DATASET is a 2-dimensional chunked dataset with dataspace:
dims[] and max_dims[] */
dataset_id = H5Dopen2(file_id, “dataset”, dapl_id);
/* Get the dataset’s datatype */
type = H5Dget_type(dataset_id);
/* Append 50 lines along the unlimited dimension (index = 0) to the dataset */
for(n = 0; n < 50; n++) {
/* Append 1 line to the dataset */
/* Whenever hitting the specified boundary i.e., every 5 lines,
the library will invoke append_cb() and then flush the dataset. */
H5DOappend(dataset_id, H5P_DEFAULT, 0, 1, type, buf);
}
:
:
:
/* counter will be equal to 10 */
:
:
:
/* The callback function */
static herr_t
append_cb(hid_t dset_id, hsize_t *cur_dims, void *_udata)
{
unsigned *count = (unsigned *)_udata;
++(*count++);
return 0;
} /* append_cb() */
| Release | Change |
| 1.10.0 | C function introduced with this release. |