Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.10.9-1
C-API Reference
User-defined ID Types

Detailed Description

The H5I module contains functions to define new identifier types. For convenience, handles of type hid_t can then be associated with the new identifier types and user objects.

New identifier types can be created by registering a new identifier type with the HDF5 library. Once a new identifier type has bee registered, it can be used to generate identifiers for user objects.

User-defined identifier types can be searched and iterated.

Like library-defined identifiers, user-defined identifiers and identifier types are reference counted, and the reference counts can be manipulated accordingly.

User-defined identifiers no longer in use should be deleted or reclaimed, and identifier types should be destroyed if they are no longer required.

CreateRead
122  herr_t free_func(void *obj)
123  {
124  printf("Calling free_func...\n");
125  H5free_memory(obj);
126  return 0;
127  }
128 
129  {
130  __label__ fail_id, fail_obj, fail_register;
131  H5I_type_t type;
132  int * obj;
133  hid_t obj_id;
134 
135  // register a new ID type
136  if ((type = H5Iregister_type(128, 1024, &free_func)) < 0) {
137  ret_val = EXIT_FAILURE;
138  goto fail_register;
139  }
140  printf("New identifier type ID: %d\n", type);
141 
142  // create a new object
143  if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) {
144  ret_val = EXIT_FAILURE;
145  goto fail_obj;
146  }
147 
148  // obtain an ID for the new object
149  if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) {
150  ret_val = EXIT_FAILURE;
151  goto fail_id;
152  }
153  printf("New object identifier: %ld\n", obj_id);
154 
155 fail_id:
156  H5Iclear_type(type, 1);
157 fail_obj:
158  H5Idestroy_type(type);
159 fail_register:;
160  }
int64_t hid_t
Definition: H5Ipublic.h:62
#define H5I_INVALID_HID
Definition: H5Ipublic.h:72
H5I_type_t
Definition: H5Ipublic.h:39
int herr_t
Definition: H5public.h:208
void * H5allocate_memory(size_t size, hbool_t clear)
Frees memory allocated by the HDF5 library.
herr_t H5free_memory(void *mem)
Frees memory allocated by the HDF5 library.
herr_t H5Iclear_type(H5I_type_t type, hbool_t force)
Deletes all identifiers of the given type.
herr_t H5Idestroy_type(H5I_type_t type)
Removes an identifier type and all identifiers within that type.
hid_t H5Iregister(H5I_type_t type, const void *object)
Registers an object under a type and returns an ID for it.
H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func)
Creates and returns a new ID type.
164  {
165  __label__ fail_query, fail_register;
166  H5I_type_t type;
167  hsize_t count;
168 
169  // register a new ID type
170  if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
171  ret_val = EXIT_FAILURE;
172  goto fail_register;
173  }
174  printf("New FOO identifier type ID: %d\n", type);
175 
176  // return the number of identifiers of TYPE currently in use
177  if (H5Inmembers(type, &count) < 0) {
178  ret_val = EXIT_FAILURE;
179  goto fail_query;
180  }
181  printf("%llu FOO identifiers in use\n", count);
182 
183 fail_query:
184  H5Idestroy_type(type);
185 fail_register:;
186  }
unsigned long long hsize_t
Definition: H5public.h:323
herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members)
Returns the number of identifiers in a given identifier type.
UpdateDelete
190  {
191  __label__ fail_id, fail_register;
192  H5I_type_t type;
193  int obj = 42;
194  hid_t obj_id;
195 
196  // register a new ID type
197  if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
198  ret_val = EXIT_FAILURE;
199  goto fail_register;
200  }
201  printf("New identifier type ID: %d\n", type);
202 
203  // obtain an ID for the new object
204  if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) {
205  ret_val = EXIT_FAILURE;
206  goto fail_id;
207  }
208  printf("New object identifier: %ld\n", obj_id);
209 
210  // bump the reference count
211  assert(H5Iinc_ref(obj_id) == 2);
212 
213  // force the deletion of all IDs regardless of reference count
214  H5Iclear_type(type, 1);
215 fail_id:
216  H5Idestroy_type(type);
217 fail_register:;
218  }
int H5Iinc_ref(hid_t id)
Increments the reference count for an object.
222  {
223  __label__ fail_register;
224  H5I_type_t type;
225 
226  // register a new ID type
227  if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
228  ret_val = EXIT_FAILURE;
229  goto fail_register;
230  }
231  printf("New identifier type ID: %d\n", type);
232 
233  // decrementing the identifier type's ref. count to 0 triggers
234  // the type to be destroyed
235  assert(H5Idec_type_ref(type) == 0);
236 
237 fail_register:;
238  }
int H5Idec_type_ref(H5I_type_t type)
Decrements the reference count on an identifier type.

Functions

hid_t H5Iregister (H5I_type_t type, const void *object)
 Registers an object under a type and returns an ID for it. More...
 
void * H5Iobject_verify (hid_t id, H5I_type_t type)
 Returns the object referenced by an ID. More...
 
void * H5Iremove_verify (hid_t id, H5I_type_t type)
 Removes an ID from its type. More...
 
H5I_type_t H5Iregister_type (size_t hash_size, unsigned reserved, H5I_free_t free_func)
 Creates and returns a new ID type. More...
 
herr_t H5Iclear_type (H5I_type_t type, hbool_t force)
 Deletes all identifiers of the given type. More...
 
herr_t H5Idestroy_type (H5I_type_t type)
 Removes an identifier type and all identifiers within that type. More...
 
int H5Iinc_type_ref (H5I_type_t type)
 Increments the reference count on an ID type. More...
 
int H5Idec_type_ref (H5I_type_t type)
 Decrements the reference count on an identifier type. More...
 
int H5Iget_type_ref (H5I_type_t type)
 Retrieves the reference count on an ID type. More...
 
void * H5Isearch (H5I_type_t type, H5I_search_func_t func, void *key)
 Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied. More...
 
herr_t H5Inmembers (H5I_type_t type, hsize_t *num_members)
 Returns the number of identifiers in a given identifier type. More...
 
htri_t H5Itype_exists (H5I_type_t type)
 Determines whether an identifier type is registered. More...
 

Function Documentation

◆ H5Iclear_type()

herr_t H5Iclear_type ( H5I_type_t  type,
hbool_t  force 
)

Deletes all identifiers of the given type.

Parameters
[in]typeIdentifier of identifier type which is to be cleared of identifiers
[in]forceWhether or not to force deletion of all identifiers
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Iclear_type() deletes all identifiers of the type identified by the argument type.

The identifier type's free function is first called on all of these identifiers to free their memory, then they are removed from the type.

If the force flag is set to false, only those identifiers whose reference counts are equal to 1 will be deleted, and all other identifiers will be entirely unchanged. If the force flag is true, all identifiers of this type will be deleted.

◆ H5Idec_type_ref()

int H5Idec_type_ref ( H5I_type_t  type)

Decrements the reference count on an identifier type.

Parameters
[in]typeThe identifier of the type whose reference count is to be decremented
Returns
Returns the current reference count on success, negative on failure.

H5Idec_type_ref() decrements the reference count on an identifier type. The reference count is used by the library to indicate when an identifier type can be destroyed. If the reference count reaches zero, this function will destroy it.

The type parameter is the identifier for the identifier type whose reference count is to be decremented. This identifier must have been created by a call to H5Iregister_type().

◆ H5Idestroy_type()

herr_t H5Idestroy_type ( H5I_type_t  type)

Removes an identifier type and all identifiers within that type.

Parameters
[in]typeIdentifier of identifier type which is to be destroyed
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Idestroy_type deletes an entire identifier type type. All identifiers of this type are destroyed and no new identifiers of this type can be registered.

The type’s free function is called on all of the identifiers which are deleted by this function, freeing their memory. In addition, all memory used by this type’s hash table is freed.

Since the H5I_type_t values of destroyed identifier types are reused when new types are registered, it is a good idea to set the variable holding the value of the destroyed type to H5I_UNINIT.

◆ H5Iget_type_ref()

int H5Iget_type_ref ( H5I_type_t  type)

Retrieves the reference count on an ID type.

Parameters
[in]typeThe identifier of the type whose reference count is to be retieved
Returns
Returns the current reference count on success, negative on failure.

H5Iget_type_ref() retrieves the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be retrieved. This identifier must have been created by a call to H5Iregister_type().

◆ H5Iinc_type_ref()

int H5Iinc_type_ref ( H5I_type_t  type)

Increments the reference count on an ID type.

Parameters
[in]typeThe identifier of the type whose reference count is to be incremented
Returns
Returns the current reference count on success, negative on failure.

H5Iinc_type_ref() increments the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be incremented. This identifier must have been created by a call to H5Iregister_type().

◆ H5Inmembers()

herr_t H5Inmembers ( H5I_type_t  type,
hsize_t num_members 
)

Returns the number of identifiers in a given identifier type.

Parameters
[in]typeThe identifier type
[out]num_membersNumber of identifiers of the specified identifier type
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Inmembers() returns the number of identifiers of the identifier type specified in type.

The number of identifiers is returned in num_members. If no identifiers of this type have been registered, the type does not exist, or it has been destroyed, num_members is returned with the value 0.

◆ H5Iobject_verify()

void* H5Iobject_verify ( hid_t  id,
H5I_type_t  type 
)

Returns the object referenced by an ID.

Parameters
[in]idID to be dereferenced
[in]typeThe identifier type
Returns
Pointer to the object referenced by id on success, NULL on failure.

H5Iobject_verify() returns a pointer to the memory referenced by id after verifying that id is of type type. This function is analogous to dereferencing a pointer in C with type checking.

Note
H5Iobject_verify() does not change the ID it is called on in any way (as opposed to H5Iremove_verify(), which removes the ID from its type’s hash table).
See also
H5Iregister()

◆ H5Iregister()

hid_t H5Iregister ( H5I_type_t  type,
const void *  object 
)

Registers an object under a type and returns an ID for it.

Parameters
[in]typeThe identifier of the type of the new ID
[in]objectPointer to object for which a new ID is created
Returns
Returns a object identifier if successful; otherwise returns H5I_INVALID_HID.

H5Iregister() creates and returns a new ID for an object.

The type parameter is the identifier for the ID type to which this new ID will belong. This identifier must have been created by a call to H5Iregister_type().

The object parameter is a pointer to the memory which the new ID will be a reference to. This pointer will be stored by the library and returned via a call to H5Iobject_verify().

◆ H5Iregister_type()

H5I_type_t H5Iregister_type ( size_t  hash_size,
unsigned  reserved,
H5I_free_t  free_func 
)

Creates and returns a new ID type.

Parameters
[in]hash_sizeMinimum hash table size (in entries) used to store IDs for the new type
[in]reservedNumber of reserved IDs for the new type
[in]free_funcFunction used to deallocate space for a single ID
Returns
Returns the type identifier on success, negative on failure.

H5Iregister_type() allocates space for a new ID type and returns an identifier for it.

The hash_size parameter indicates the minimum size of the hash table used to store IDs in the new type.

The reserved parameter indicates the number of IDs in this new type to be reserved. Reserved IDs are valid IDs which are not associated with any storage within the library.

The free_func parameter is a function pointer to a function which returns an herr_t and accepts a void*. The purpose of this function is to deallocate memory for a single ID. It will be called by H5Iclear_type() and H5Idestroy_type() on each ID. This function is NOT called by H5Iremove_verify(). The void* will be the same pointer which was passed in to the H5Iregister() function. The free_func function should return 0 on success and -1 on failure.

◆ H5Iremove_verify()

void* H5Iremove_verify ( hid_t  id,
H5I_type_t  type 
)

Removes an ID from its type.

Parameters
[in]idThe ID to be removed from its type
[in]typeThe identifier type
Returns
Returns a pointer to the memory referred to by id on success, NULL on failure.

H5Iremove_verify() first ensures that id belongs to type. If so, it removes id from its type and returns the pointer to the memory it referred to. This pointer is the same pointer that was placed in storage by H5Iregister(). If id does not belong to type, then NULL is returned.

The id parameter is the ID which is to be removed from its type.

The type parameter is the identifier for the ID type which id is supposed to belong to. This identifier must have been created by a call to H5Iregister_type().

Note
This function does NOT deallocate the memory that id refers to. The pointer returned by H5Iregister() must be deallocated by the user to avoid memory leaks.

◆ H5Isearch()

void* H5Isearch ( H5I_type_t  type,
H5I_search_func_t  func,
void *  key 
)

Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied.

Parameters
[in]typeThe identifier of the type to be searched
[in]funcThe function defining the search criteria
[in]keyA key for the search function
Returns
Returns a pointer to the object which satisfies the search function on success, NULL on failure.

H5Isearch() searches through a given ID type to find an object that satisfies the criteria defined by func. If such an object is found, the pointer to the memory containing this object is returned. Otherwise, NULL is returned. To do this, func is called on every member of type type. The first member to satisfy func is returned.

The type parameter is the identifier for the ID type which is to be searched. This identifier must have been created by a call to H5Iregister_type().

The parameter func is a function pointer to a function which takes three parameters. The first parameter is a void* and will be a pointer to the object to be tested. This is the same object that was placed in storage using H5Iregister(). The second parameter is a hid_t and is the ID of the object to be tested. The last parameter is a void*. This is the key parameter and can be used however the user finds helpful, or it can be ignored if it is not needed. func returns 0 if the object it is testing does not pass its criteria. A non-zero value should be returned if the object does pass its criteria. H5I_search_func_t is defined in H5Ipublic.h and is shown below.

typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
int(* H5I_search_func_t)(void *obj, hid_t id, void *key)
Definition: H5Ipublic.h:87

The key parameter will be passed to the search function as a parameter. It can be used to further define the search at run-time.

◆ H5Itype_exists()

htri_t H5Itype_exists ( H5I_type_t  type)

Determines whether an identifier type is registered.

Parameters
[in]typeIdentifier type
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Itype_exists() determines whether the given identifier type, type, is registered with the library.

Since
1.8.0