H5Pset_local_heap_size_hint
(
hid_t gcpl_id
,
size_t size_hint
)
H5Pset_local_heap_size_hint
is used with original-style
HDF5 groups (see “Motivation” below) to specify
the anticipated maximum local heap size, size_hint
,
for groups created with the group creation property list
gcpl_id
.
The HDF5 Library then uses size_hint
to allocate contiguous local heap space in the file for each group
created with gcpl_id
.
For groups with many members or very few members, an appropriate initial
value of size_hint
would be the anticipated number of group
members times the average length of group member names, plus a small margin:
size_hint = max_number_of_group_members * (average_length_of_group_member_link_names + 2)
If it is known that there will be groups with zero members,
the use of a group creation property list with size_hint
set to to 1
(one) will guarantee the smallest possible
local heap for each of those groups.
Setting size_hint
to zero (0
) causes the
library to make a reasonable estimate for the default local heap size.
H5Pset_local_heap_size_hint
is useful for tuning
file size when files contain original-style groups with
either zero members or very large numbers of members.
The original style of HDF5 groups, the only style available prior to HDF5 Release 1.8.0, was well-suited for moderate-sized groups but was not optimized for either very small or very large groups. This original style remains the default, but two new group implementations were introduced in HDF5 Release 1.8.0: compact groups to accomodate zero to small numbers of members and indexed groups for thousands or tens of thousands of members ... or millions, if that's what your application requires.
The local heap size hint, size_hint
, is a
performance tuning parameter for original-style groups.
As indicated above, an HDF5 group may have zero, a handful,
or tens of thousands of members.
Since the original style of HDF5 groups stores the metadata
for all of these group members in a uniform format in a local heap,
the size of that metadata (and hence, the size of the local heap)
can vary wildly from group to group.
To intelligently allocate space and to avoid unnecessary fragmentation
of the local heap, it can be valuable to provide the library
with a hint as to the local heap’s likely eventual size.
This can be particularly valuable when it is known that a group
will eventually have a great many members.
It can also be useful in conserving space in a file when
it is known that certain groups will never have any members.
hid_t gcpl_id |
IN: Group creation property list identifier |
size_t size_hint |
IN: Anticipated maximum size in bytes of local heap |
SUBROUTINE h5pset_local_heap_size_hint_f(gcpl_id, size_hint, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id INTEGER(SIZE_T), INTENT(IN) :: size_hint ! Hint for size of local heap INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_local_heap_size_hint_f
Release | Change |
1.8.0 | Function introduced in this release. |