Specifies the anticipated maximum size of = a local heap
H5P_SET_LOCAL_HEAP_SIZE_HINT ( gcpl_id, size_hint )
herr_t H5Pset_local_heap_size_hint(
hid_t gcpl_id,
size_t size_hint
)
hid_t gcpl_id 
IN: Group creation property list identifier 
size_t size_hint =

IN: Anticipated maximum size in bytes of local h= eap 
H5P_SET_LOCAL_HEAP_SIZE_HINT is used with originalstyle HDF5 groups (se=
e =E2=80=9CMotivation=E2=80=9D below) to specify the anticipated maximum lo=
cal heap size, size_hint
, for groups created with the group cr=
eation property list gcpl_id
. The HDF5 library then uses size_hint to allocate contiguous local heap space in the file for e=
ach 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 m=
embers times the average length of group member names, plus a small margin:=
size_hint =3D max_number_of_group_members *=20 (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 t=
hose groups.
Setting size_hint
to zero (0
) causes the libra=
ry to make a reasonable estimate for the default local heap size.
In situations where backwardcompatibility is required, specifically, wh= en libraries prior to HDF5 Release 1.8.0 may be used to read the file, grou= ps must be created and maintained in the original style. This is HDF5=E2=80= =99s default behavior. If backward compatibility with pre1.8.0 libraries i= s not a concern, greater efficiencies can be obtained with the newformat c= ompact and indexed groups. See Group imple= mentations in HDF5 in the H5G API introduction (at the bottom).
H5P_SET_LOCAL_HEAP_SIZE_HINT is useful for tuning file size when files c= ontain originalstyle groups with either zero members or very large numbers= of members.
The original style of HDF5 groups, the only style available prior to HDF= 5 Release 1.8.0, was wellsuited for moderatesized groups but was not opti= mized for either very small or very large groups. This original style remai= ns the default, but two new group implementations were introduced in HDF5 R= elease 1.8.0: compact groups to accommodate zero to small numbers of member= s and indexed groups for thousands or tens of thousands of members ... or m= illions, if that's what your application requires.
The local heap size hint, size_hint
, is a performance tunin=
g parameter for originalstyle 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 m=
embers 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=E2=80=99s likely eventual size. This can be particularly valuab=
le 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.
Returns a nonnegative value if successful; otherwise returns a negative= value.
Coming Soon!
Release =  Change 

1.8.0  Function introduced in this release. 
 Last Modified: May 17, 2019  01:54 PM