Loading...
Searching...
No Matches
Handle Table for Reference Counting Data
Globus Common API

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.

## 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

## GLOBUS_NULL_HANDLE

#define GLOBUS_NULL_HANDLE

Invalid handle value

## Typedef Documentation

## globus_handle_destructor_t

typedef void(* globus_handle_destructor_t) (void *datum)

Handle datum destructor.

Parameters

  datum | Datum to destroy

## Function Documentation

## globus_handle_table_decrement_reference()

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.

## globus_handle_table_destroy()

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_handle_table_increment_reference()

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_handle_table_increment_reference_by()

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.

## globus_handle_table_init()

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_table_insert()

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.

## globus_handle_table_lookup()

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.