Hi all,
We need to start thinking about what the new group API will look like.
Here's a quick draft of a high level view from the changes I can think of.
Please give me feedback about your ideas for this API. I'm also going to
write up a draft for the API renaming proposal, which will affect the changes
to the group API, but shouldn't depend on it.
Quincey
========================================================================
NOTE #1: These changes are mainly ramifications from the addition of an
[optional] index that allows applications to access objects in a group
according to the order they were created.
NOTE #2: We still need to decide on scheme for re-naming existing functions
when their parameters change.
Existing API routine changes:
============================
Old Name: Purpose: Change:
========= ======== ======
H5Gcreate Create new group Will need to drop 'size_hint'
parameter and acquire "group
creation" and "group access"
property lists
H5Gopen Open an existing Add "group access" property
group list
H5Gclose Close a group ID <none>
H5Gset_comment Set a "comment" on a <none> (deprecated)
group
H5Gget_comment Get the "comment" on a <none> (deprecated)
group
H5Glink/H5Glink2 Creates a link to an <none>
object in another group
by name in the other
group
H5Gmode/H5Gmove2 Renames a link to an <none>
object in current group
by name
H5Giterate Iterate through objects Change to allow choice of which
in a group, with user index to use (and direction?).
callback routine
H5Gget_objinfo Retrieve information Update H5G_stat_t with any new
about an object in a information. Possibly add
group H5Gget_objinfo_by_idx routine?
Absorb H5Gget_<foo>_by_idx
routines?
H5Gget_num_objs Retrieve number of <none>
objects in a group
H5Gget_objname_by_idx Retrieve name of n'th Needs a "type of index"
object in a group, parameter, in order to choose
according to link name index to use to compute the
order "n'th object" of.
H5Gget_objtype_by_idx Retrieve type of n'th Needs a "type of index"
object in a group, parameter, in order to choose
according to link name index to use to compute the
order "n'th object" of.
Added API routines:
==================
Name: Purpose:
========= =======
H5Glink_order Create a link to an object in another group by creation
order in the other group.
H5Gunlink_order Remove the n'th object (by creation order) in a group.
H5Gchange_time Change the creation time of an object in a group,
potentially changing its position in creation order.
H5Gget_linkval_by_idx Retrieve the link information about a soft link, using
the order with an index.
H5Gopen_by_idx Open the n'th object in a group, accordding to
the order with an index.
New property lists:
==================
Name: Purpose:
===== =======
"Group Creation" Control various parameters of a group, like it's B-tree
properties and whether it has an index allowing it
track the order that objects are created. Possibly
other parameters as well.
"Group Access" Control various parameters of accessing a group, like
possibly the default index to use for various
operations, etc.
