Name: H5Pset_local_heap_size_hint
Signature:
  herr_t `H5Pset_local_heap_size_hint`( hid_t `gcpl_id`, size_t `size_hint` )

Purpose:
  Specifies the anticipated maximum size of a local heap.

Description:
  `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.

Motivation:
  In situations where backward-compatibility is required, specifically, when libraries prior to HDF5 Release 1.8.0 may be used to read the file, groups must be created and maintained in the original style. This is HDF5’s default behavior. If backward compatibility with pre-1.8.0 libraries is not a concern, greater efficiencies can be obtained with the new-format compact and indexed groups. See “Group implementations in HDF5” in the H5G API introduction.

  `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.

Parameters:

  hid_t `gcpl_id` | IN: Group creation property list identifier
  size_t `size_hint` | IN: Anticipated maximum size in bytes of local heap

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5pset_local_heap_size_hint_f

      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

History:

  Release | Change
  1.8.0 | Function introduced in this release.