NAME

       globus_handle_table - Handle Table for Reference Counting Data

        - Handle Table for Reference Counting Data.

SYNOPSIS

   Macros
       #define GLOBUS_NULL_HANDLE

   Typedefs
       typedef struct globus_l_handle_table_s * globus_handle_table_t
           Handle table abstract type.
       typedef int globus_handle_t
           Handle abstract type.
       typedef void(* globus_handle_destructor_t) (void *datum)
           Handle datum destructor.

   Functions
       int globus_handle_table_init (globus_handle_table_t *handle_table,
           globus_handle_destructor_t destructor)
       int globus_handle_table_destroy (globus_handle_table_t *handle_table)
           Destroy a handle table.
       globus_handle_t globus_handle_table_insert (globus_handle_table_t *handle_table, void
           *value, int initial_refs)
       globus_bool_t globus_handle_table_increment_reference_by (globus_handle_table_t
           *handle_table, globus_handle_t handle, unsigned int inc)
           Increment the reference count for handle.
       globus_bool_t globus_handle_table_decrement_reference (globus_handle_table_t
           *handle_table, globus_handle_t handle)
           Remove a reference to a handle.
       globus_bool_t globus_handle_table_increment_reference (globus_handle_table_t
           *handle_table, globus_handle_t handle)
           Add a reference to a handle table entry.
       void * globus_handle_table_lookup (globus_handle_table_t *handle_table, globus_handle_t
           handle)
           Resolve a handle its datum.

Detailed Description

       Handle Table for Reference Counting Data.

       The globus_handle_table_t abstraction provides a reference-counting handle table to
       automatically free data when there are no more references to it. Each datum in the
       globus_handle_table_t container has a count associated with it which may be incremented
       and decremented in single steps or by an increment. While a handle has any references to
       it, the globus_handle_table_lookup() will return the datum associated with the handle,
       otherwise it will return NULL. The value of a globus_handle_t is not reused until INT_MAX
       data have been inserted into the handle table.

Macro Definition Documentation

   #define GLOBUS_NULL_HANDLE
       Invalid handle value

Typedef Documentation

   typedef void(* globus_handle_destructor_t) (void *datum)
       Handle datum destructor.

       Parameters
           datum Datum to destroy

Function Documentation

   globus_bool_t globus_handle_table_decrement_reference (globus_handle_table_t * handle_table,
       globus_handle_t handle)
       Remove a reference to a handle. Remove a reference to a handle table entry, calling its
       destructor if no more references exist for the handle.

       Parameters
           handle_table The table that the handle was created in.
           handle
            The handle to a datum to decrement the reference count for.

       Returns
           The globus_handle_table_decrement_reference() function returns a boolean value
           indicating whether the handle still references a valid datum.

   int globus_handle_table_destroy (globus_handle_table_t * handle_table)
       Destroy a handle table. Destroy a handle table and call the destructor for all objects
       associated with it.

       Parameters
           handle_table Pointer to the handle table to destroy

   globus_bool_t globus_handle_table_increment_reference (globus_handle_table_t * handle_table,
       globus_handle_t handle)
       Add a reference to a handle table entry.

       Parameters
           handle_table The table that the handle was created in.
           handle
            The handle to a datum to increment the reference count for.

       Returns
           The globus_handle_table_increment_reference() function returns a boolean value
           indicating whether the handle still references a valid datum.

   globus_bool_t globus_handle_table_increment_reference_by (globus_handle_table_t *
       handle_table, globus_handle_t handle, unsigned int inc)
       Increment the reference count for handle.

       Parameters
           handle_table The table that the handle was created in.
           handle
            The handle to a datum to increment the reference count for.
           inc The number of references to add the handle.

       Returns
           The globus_handle_table_increment_reference_by() function returns a boolean value
           indicating whether the handle still references a valid datum.

   int globus_handle_table_init (globus_handle_table_t * handle_table, globus_handle_destructor_t
       destructor)
       Initialize a table of unique reference counted handles.

       Parameters
           handle_table the table of unique handles we want to use.
           destructor Function to call to free the data associated with a handle when the
           handle's reference count reaches 0 or the handle table is destroyed.

   globus_handle_t globus_handle_table_insert (globus_handle_table_t * handle_table, void *
       value, int initial_refs)
       Insert a datum into a handle table

       Insert a value into the handle table, and return a unique handle to it.

       Parameters
           handle_table Handle table to add the value to
           value The value to insert into the table
           initial_refs The initial reference count of this value in the table

       Returns
           The globus_handle_table_insert() function returns a unique handle to value.

   void * globus_handle_table_lookup (globus_handle_table_t * handle_table, globus_handle_t
       handle)
       Resolve a handle its datum.

       Parameters
           handle_table The table that the handle was created in.
           handle
            The handle to a datum to resolve

       Returns
           The globus_handle_table_lookup() function returns the datum associated with the handle
           in the handle table, or NULL if the handle does not reference valid data.

Author

       Generated automatically by Doxygen for globus_common from the source code.