Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Typedefs | Functions
Handle Table for Reference Counting Data

Handle Table for Reference Counting Data. More...

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

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. More...
 
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. More...
 
globus_bool_t globus_handle_table_decrement_reference (globus_handle_table_t *handle_table, globus_handle_t handle)
 Remove a reference to a handle. More...
 
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. More...
 
void * globus_handle_table_lookup (globus_handle_table_t *handle_table, globus_handle_t handle)
 Resolve a handle its datum. More...
 

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
datumDatum 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_tableThe table that the handle was created in.
handleThe 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_tablePointer 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_tableThe table that the handle was created in.
handleThe 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_tableThe table that the handle was created in.
handleThe handle to a datum to increment the reference count for.
incThe 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_tablethe table of unique handles we want to use.
destructorFunction 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_tableHandle table to add the value to
valueThe value to insert into the table
initial_refsThe 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_tableThe table that the handle was created in.
handleThe 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.