The HDF5 Identifier Interface

Introduction

The HDF5 Identifier interface (H5I) manages identifiers (type hid_t) that serve as handles to HDF5 objects and resources. Identifiers provide an abstraction layer between applications and the internal HDF5 library structures, enabling safe and efficient object management.

Every HDF5 object—file, group, dataset, datatype, dataspace, attribute, property list—is accessed through an identifier. The H5I interface provides functions to query, validate, and manage these identifiers and their associated resources.

Identifier Types

HDF5 defines several built-in identifier types:

H5I_FILE - File identifiers
H5I_GROUP - Group identifiers
H5I_DATATYPE - Datatype identifiers
H5I_DATASPACE - Dataspace identifiers
H5I_DATASET - Dataset identifiers
H5I_ATTR - Attribute identifiers
H5I_MAP - Map identifiers
H5I_VFL - Virtual File Layer driver identifiers
H5I_VOL - Virtual Object Layer connector identifiers
Property list identifiers (various classes)

Each identifier type is managed independently with its own reference counting system.

Reference Counting

Identifiers use reference counting to manage object lifetimes. When an identifier is created, its reference count is set to 1. The reference count can be manipulated to control when resources are released:

H5Iget_ref retrieves the current reference count
H5Iinc_ref increments the reference count
H5Idec_ref decrements the reference count

When a reference count reaches zero, the associated resources are automatically released.

Identifier Validation

The H5I interface provides functions to validate identifiers:

H5Iis_valid checks if an identifier is valid and has a positive reference count
H5Iget_type retrieves the type of an identifier
H5Itype_exists checks if an identifier type is registered

Querying Identifiers

Applications can retrieve information about objects through their identifiers:

H5Iget_name retrieves the name of an object (for files, groups, datasets, etc.)
H5Iget_file_id retrieves the file identifier associated with any object

These functions are particularly useful for debugging and logging.

User-Defined Identifier Types

Advanced applications can register custom identifier types using H5Iregister. This allows user-defined objects to benefit from HDF5's identifier management:

Automatic reference counting
Type safety through identifier types
Integration with HDF5's resource management

Custom identifier types can be destroyed using H5Idestroy_type when no longer needed.

Identifier Iteration

The H5I interface allows iteration over all identifiers of a given type:

H5Iiterate iterates over identifiers of a specified type with a callback function
H5Inmembers returns the number of identifiers of a given type

This is useful for resource tracking, debugging, and cleanup operations.

Summary

The H5I identifier interface provides essential functionality:

Safe handles to HDF5 objects and resources
Reference counting for automatic resource management
Type checking and validation
Object information retrieval
Support for user-defined identifier types
Iteration capabilities for resource tracking

Proper identifier management is fundamental to writing robust HDF5 applications that efficiently manage memory and avoid resource leaks.

Navigate back: Main / HDF5 User Guide