Handle Table for Reference Counting Data
[Globus Common API]

Defines
#define	GLOBUS_NULL_HANDLE
Typedefs
typedef 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

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.

---

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

---