H5P_SET_FILE_IMAGE_CALLBACKS sets callback functions for working with file images in memory.

H5P_SET_FILE_IMAGE_CALLBACKS allows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.

H5P_SET_FILE_IMAGE_CALLBACKS must be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.

The callback routines set up by H5P_SET_FILE_IMAGE_CALLBACKS are invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.

Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver’s internal buffer, potentially allowing optimizations such as avoiding large malloc and memcpy operations, or to perform detailed logging.

From the perspective of the HDF5 library, the operations of the image_malloc, image_memcpy, image_realloc, and image_free callbacks must be identical to those of the corresponding C standard library calls (malloc, memcpy, realloc, and free). While the operations must be identical, the file image callbacks have more parameters. The return values of image_malloc and image_realloc are identical to the return values of malloc and realloc. The return values of image_memcpy and image_free differ from the return values of memcpy and free in that the return values of image_memcpy and image_free can also indicate failure.

The callbacks and their parameters, along with a struct and an ENUM required for their use, are described below.

Callback struct and ENUM:
The callback functions set up by H5P_SET_FILE_IMAGE_CALLBACKS use a struct and an ENUM that are defined as follows

The struct H5_file_image_callbacks_t serves as a container for the callback functions and a pointer to user-supplied data. The struct is defined as follows:

  typedef struct
    {
        void *(*image_malloc)(size_t size, H5_file_image_op_t file_image_op,
                        void *udata);
        void *(*image_memcpy)(void *dest, const void *src, size_t size,
                        H5_file_image_op_t file_image_op, void *udata);
        void *(*image_realloc)(void *ptr, size_t size,
                        H5_file_image_op_t file_image_op, void *udata);
        herr_t (*image_free)(void *ptr, H5_file_image_op_t file_image_op,
                        void *udata);
        void *(*udata_copy)(void *udata); 
        herr_t (*udata_free)(void *udata); 
        void *udata;
    } H5_file_image_callbacks_t;

Elements of the ENUM H5_file_image_op_t are used by the callbacks to invoke certain operations on file images. The ENUM is defined as follows:

    typedef enum
    {
        H5_FILE_IMAGE_OP_PROPERTY_LIST_SET, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_COPY, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_GET, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, 
        H5_FILE_IMAGE_OP_FILE_OPEN, 
        H5_FILE_IMAGE_OP_FILE_RESIZE, 
        H5_FILE_IMAGE_OP_FILE_CLOSE
    } H5_file_image_op_t;

The elements of the H5_file_image_op_t ENUM are used in the callbacks for the following purposes:

Callback functions
The image_malloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library malloc() call.

Signature in H5_file_image_callbacks_t:

void *(*image_malloc) ( size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

The image_memcpy callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library memcopy() call, except that it returns a NULL on failure. (The memcpy C Library routine is defined to return the dest parameter in all cases.)

Setting image_memcpy to NULL indicates that HDF5 should invoke the standard C library memcpy() routine when copying buffers.

Signature in H5_file_image_callbacks_t:

void *(*image_memcpy) ( void *dest, const void *src, size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

The image_realloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library realloc() call.

Setting image_realloc to NULL indicates that HDF5 should invoke the standard C library realloc() routine when resizing file image buffers.

Signature in H5_file_image_callbacks_t:

void *(*image_realloc) ( void *ptr, size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

The image_free callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library free() call, except that it will return 0 (SUCCEED) on success and -1 (FAIL) on failure.

Setting image_free to NULL indicates that HDF5 should invoke the standard C library free() routine when releasing file image buffers.

Signature in H5_file_image_callbacks_t:

herr_t (*image_free) ( void *ptr, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

The udata_copy callback contains a pointer to a function that, from the perspective of HDF5, allocates a buffer of suitable size, copies the contents of the supplied udata into the new buffer, and returns the address of the new buffer. The function returns NULL on failure. This function is necessary if a non-NULL udata parameter is supplied, so that property lists containing the image callbacks can be copied. If the udata parameter below is NULL, then this parameter should be NULL as well.

Signature in H5_file_image_callbacks_t:

void *(*udata_copy) ( void *udata )

Parameters:

The udata_free callback contains a pointer to a function that, from the perspective of HDF5, frees a user data block. This function is necessary if a non-NULL udata parameter is supplied so that property lists containing image callbacks can be discarded without a memory leak. If the udata parameter below is NULL, this parameter should be NULL as well.

Signature in H5_file_image_callbacks_t:

herr_t (*udata_free) ( void *udata )

Parameters:

udata, the final field in the H5_file_image_callbacks_t struct, provides a pointer to user-defined data. This pointer will be passed to the image_malloc, image_memcpy, image_realloc, and image_free callbacks. Define udata as NULL if no user-defined data is provided.

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes: Due to interactions between this function and H5P_SET_FILE_IMAGE and H5P_GET_FILE_IMAGE, H5P_SET_FILE_IMAGE_CALLBACKS will fail if a file image has already been set in the target file access property list, fapl_id.

Coming Soon!