Revising Numeric Overflows in HDF5

Document's Audience:

• Current H5 library designers and knowledgable external developers.

Background Reading:

The HDF5 reference manual sections for H5Pset_type_conv_cb and H5Pget_type_conv_cb:

H5Pset_type_conv_cb

H5Pget_type_conv_cb

(H5Tset_overflow and H5Tget_overflow have been removed from the HDF5 Library. This note inserted: January 2010.)

This section of the HDF5 User’s Guide briefly mentions conversion overflows:

Datatype Conversion and Selection

The netCDF user guide section on type conversion:

Type Conversion

The netCDF user guide section on fill values:

Set Fill Mode for Writes: nc_set_fill

Introduction:

What is this document about?

This document describes some limitations of the current HDF5 datatype conversion overflow behavior, new requirements for the overflow behavior and describes a solution for covering those requirements.

How does the overflow callback currently operate?

The HDF5 library's current behavior when converting a value from one datatype to another is to issue a call to the "overflow" callback whenever a source value is outside of the range of values representable by the destination datatype. If the overflow callback is not set or is set, but indicates that it hasn't handled the overflow (by returning a negative value when called), the destination value is set to either the maximum or minimum destination value (depending if the source value was beyond the maximum or minimum destination value respectively). The development branch of the HDF5 library (v1.7.x) extends this behavior to it's support for int <-> float type conversions.

For example, when converting from a signed 16-bit integer to an unsigned 16-bit integer, negative source values would trigger a call to the overflow callback, and if it didn't exist or handle the overflow, the minimum unsigned 16-bit integer (0) would be used as the destination value. Likewise, when converting from a signed 32-bit integer to a signed 16-bit integer, source values greater than 32767 or less than -32768 would trigger a call to the overflow callback and would be set to 32767 or -32768 (respectively) if the overflow callback didn't exist or didn't handle the exception.

What is the prototype for the current conversion callback?

Here's the prototype for the overflow callback routine:

herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf);

New Requirements:

There are several new requirements listed here, in order of decreasing importance:

• Support netCDF-3 type conversion behavior. It's not obvious from the background information about the netCDF-3 above, but netCDF-3 replaces "out of bound" values with the fill value for the dataset, in addition to issuing an error. We will need to be able to pass the appropriate fill-value for a datatype to the overflow callback in order to support this use case.
• Indicate type of "overflow". Now that we are performing int <-> float type conversions, there are different kinds of conversion exceptions that are possible. There are "range" errors (as we've previously had) and now there can be "loss of precision" errors for int -> float conversions and "truncation" errors for float -> int conversions. The type of the conversion exception should be passed to the overflow routine. This is particularly important for netCDF-3 emulation, which only replaces the destination value with the fill value for "range" errors, not for the other types of errors.
• Allow for "user data" to reach the callback. The general rule in HDF5 callbacks is to allow a "void *" which the application sets to be passed in to a callback routine. This would allow applications to pass along any custom information that the callback would need. The fill value mentioned above can be passed into the callback through this "void *".
• Make the callback a non-global setting. Currently there is one global "overflow" callback for the HDF5 library. It should be possible to set a callback on a per-data-transfer basis.
• Allow for the callback to indicate the conversion should stop. Currently the conversion of data values continues through the entire buffer of values to convert. It would be nice if there were a way for the callback routine to indicate that further values should not be converted.

Suggested Changes:

To accomodate the requirements above, changing the prototype of the "overflow" callback is necessary, as well as attaching it to a data transfer property list and changing the library's behavior for the return values of the callback. I would also suggest changing the name from an "overflow" callback to the more generic "type conversion exception callback".

After accomodating the changes above, the prototype would look like this:

H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type,
        hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data);
    

The parameters are as follows:

• exception_type - The type of exception (enum described below).
• src_id - A datatype ID describing the source datatype.
• dst_id - A datatype ID describing the destination datatype.
• src_buf - A pointer to the buffer containing the source value.
• dst_buf - A pointer to the buffer where the destination value should be placed.
• user_data - A pointer to the "user data" set by the application that registered the conversion callback.

The H5T_conv_except_t enumerated type has the following values:

• H5T_CONV_EXCEPT_RANGE_HI - The source value is greater than the range of values that can be encoded in the destination value.
• H5T_CONV_EXCEPT_RANGE_LOW - The source value is less than the range of values that can be encoded in the destination value.
• H5T_CONV_EXCEPT_PRECISION - The source value will suffer a loss of precision when it is represented in the destination type. (This generally occurs when very large integers are converted to floating-point types)
• H5T_CONV_EXCEPT_TRUNCATE - The source value will suffer a truncation in value when it is represented in the destination type. (This generally occurs when floating-point values with fractional values are converted to integer datatypes)

The return value from conversion callbacks is H5T_conv_ret_t, a new enumerated type with the following values:

• H5T_CONV_ABORT - Abort type conversion immediately (-1).
• H5T_CONV_UNHANDLED - Conversion callback did not handled the conversion exception and the HDF5 library should perform whatever default conversion it normally applies (0).
• H5T_CONV_HANDLED - Conversion callback handled the conversion exception and the HDF5 library should not perform whatever default conversion it normally applies (1).

Additionally, the H5Tset_overflow and H5Tget_overflow routines would be retired in favor of the following routines:

Name:

H5Pset_type_conv_cb

Purpose:

Register a type conversion callback.

Signature:

herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void *operator_data)

Parameters:

hid_t dxpl_id

IN: ID of dataset transfer property list.

H5T_conv_except_func_t *op

IN: Pointer to callback function to call for when a type conversion exception occurs.

void *operator_data

IN: Pointer that will be passed to callback function when a type conversion exception occurs.

Return Value:

Returns non-negative on success, negative on failure.

Description:

This function sets the callback function that the HDF5 library will call when a type conversion exception occurs. Type conversion exceptions occur under the following circumstances:

• A source value is outside the range of values able to be represented with the destination value (a range error).
• A source value would lose precision when converted to a value in the destination type (a loss of precision error).
• A source value would have it's value truncated when converted to a value in the destination type (a truncation error).

The conversion exception callback (H5T_conv_except_func_t) has the following prototype: (QAK: Fill in description from above when creating final reference manual page)

Name:

H5Pget_type_conv_cb

Purpose:

Retrieve the type conversion callback.

Signature:

herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t **op, void **operator_data)

Parameters:

hid_t dxpl_id

IN: ID of dataset transfer property list.

H5T_conv_except_func_t **op

OUT: Pointer to location to place pointer to type conversion exception callback function.

void **operator_data

OUT: Pointer to location to place pointer that will be passed to type conversion exception callback function when a type conversion exception occurs.

Return Value:

Returns non-negative on success, negative on failure.

Description:

This function retrieves the callback function that the HDF5 library will call when a type conversion exception occurs.

Compatibility With Version 1.6:

As we try to switch the API from H5Tset(get)_overflow to H5Pset(get)_type_conv_cb, we may encounter backward compatibility issue. We have a few options here:

Option 1

Simply discard the old API functions(H5Tset(get)_overflow). This is an easy solution. Hopefully, there are not many major users having these functions in their program. Those failing programs have to migrate to the new design with functions H5Pset(get)_type_conv_cb.

Option 2

Keep the old API functions for some time during the transition. User programs do not have to adopt the new functions. In case someone happens to set both of the old and new callback functions, we give the new one green light to proceed.

Option 3

Keep the names of the old API functions but return error messages when they are executed. Just remind users there are new API functions available.

Discussion:

With the above changes to the library, the datatype conversion code will be able to fulfill all the new requirements listed. Supporting the new type conversion exception callback and detecting the new exception types (loss of precision and truncation) will require some additional coding, but not a huge amount. Adding support for detecting the new exception types will make the int <-> float conversions slightly slower and more complex though.

If fill value is needed when conversion exception happens, it can be passed in through the user data(a void pointer) in the callback or can be made a global variable. To find the fill value is user's responsibility. They can retrieve it from the dataset transfer property list easily.