[svn-r113] Added mechanism for reference counting IDs. This is to facilitate sharing

an ID between multiple interfaces in memory.  Changes included adding a
parameter to the H5Ainit_group call for the function to call to free the
structure associated with an ID when its reference count drops to zero and
two new function calls: H5Ainc_ref & H5Adec_ref which increment and decrement
the reference count of IDs.  Its still possible to call H5Aremove_atom on
a ID with multiple references, leaving dangling IDs in memory...

1 files changed, 35 insertions, 2 deletions

diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 8bc5b7f..36cceed 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -70,9 +70,10 @@ extern "C" {
     Returns SUCCEED if successful and FAIL otherwise
 
 *******************************************************************************/
-intn H5Ainit_group(group_t grp,      /* IN: Group to initialize */
+intn H5Ainit_group(group_t grp,     /* IN: Group to initialize */
     intn hash_size,                 /* IN: Minimum hash table size to use for group */
-    uintn reserved                  /* IN: Number of hash table entries to reserve */
+    uintn reserved,                 /* IN: Number of hash table entries to reserve */
+    void (*free_func)(void *)       /* IN: Function to call when releasing ref counted objects */
 );
 
 /******************************************************************************
@@ -114,6 +115,21 @@ hid_t H5Aregister_atom(group_t grp,     /* IN: Group to register the object in *
 
 /******************************************************************************
  NAME
+     H5Ainc_ref - Adds a reference to a reference counted atom.
+
+ DESCRIPTION
+    Increments the number of references outstanding for an atom.  This will
+    fail if the group is not a reference counted group.
+
+ RETURNS
+    SUCCEED/FAIL
+
+*******************************************************************************/
+intn H5Ainc_ref(hid_t atm   /* IN: Atom to increment reference count for */
+);
+
+/******************************************************************************
+ NAME
      H5Aatom_object - Returns to the object ptr for the atom 
 
  DESCRIPTION
@@ -156,6 +172,23 @@ VOIDP H5Aremove_atom(hid_t atm   /* IN: Atom to remove */
 
 /******************************************************************************
  NAME
+     H5Adec_ref - Decrements a reference to a reference counted atom.
+
+ DESCRIPTION
+    Decrements the number of references outstanding for an atom.  This will
+    fail if the group is not a reference counted group.  The atom group's
+    'free' function will be called for the atom if the reference count for the
+    atom reaches 0.
+
+ RETURNS
+    SUCCEED/FAIL
+
+*******************************************************************************/
+intn H5Adec_ref(hid_t atm   /* IN: Atom to decrement reference count for */
+);
+
+/******************************************************************************
+ NAME
      H5Asearch_atom - Search for an object in a group and get it's pointer.
 
  DESCRIPTION