.TH "globus_handle_table" 3 "Version 18.14" "globus_common" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_handle_table \- Handle Table for Reference Counting Data
.PP
 \- Handle Table for Reference Counting Data\&.  

.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBGLOBUS_NULL_HANDLE\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct globus_l_handle_table_s * \fBglobus_handle_table_t\fP"
.br
.RI "Handle table abstract type\&. "
.ti -1c
.RI "typedef int \fBglobus_handle_t\fP"
.br
.RI "Handle abstract type\&. "
.ti -1c
.RI "typedef void(* \fBglobus_handle_destructor_t\fP) (void *datum)"
.br
.RI "Handle datum destructor\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBglobus_handle_table_init\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_destructor_t\fP destructor)"
.br
.ti -1c
.RI "int \fBglobus_handle_table_destroy\fP (\fBglobus_handle_table_t\fP *handle_table)"
.br
.RI "Destroy a handle table\&. "
.ti -1c
.RI "\fBglobus_handle_t\fP \fBglobus_handle_table_insert\fP (\fBglobus_handle_table_t\fP *handle_table, void *value, int initial_refs)"
.br
.ti -1c
.RI "\fBglobus_bool_t\fP \fBglobus_handle_table_increment_reference_by\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_t\fP handle, unsigned int inc)"
.br
.RI "Increment the reference count for handle\&. "
.ti -1c
.RI "\fBglobus_bool_t\fP \fBglobus_handle_table_decrement_reference\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_t\fP handle)"
.br
.RI "Remove a reference to a handle\&. "
.ti -1c
.RI "\fBglobus_bool_t\fP \fBglobus_handle_table_increment_reference\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_t\fP handle)"
.br
.RI "Add a reference to a handle table entry\&. "
.ti -1c
.RI "void * \fBglobus_handle_table_lookup\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_t\fP handle)"
.br
.RI "Resolve a handle its datum\&. "
.in -1c
.SH "Detailed Description"
.PP 
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 \fBglobus_handle_table_lookup()\fP 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\&. 
.SH "Macro Definition Documentation"
.PP 
.SS "#define GLOBUS_NULL_HANDLE"
Invalid handle value 
.SH "Typedef Documentation"
.PP 
.SS "typedef void(* globus_handle_destructor_t) (void *datum)"

.PP
Handle datum destructor\&. 
.PP
\fBParameters\fP
.RS 4
\fIdatum\fP Datum to destroy 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "\fBglobus_bool_t\fP globus_handle_table_decrement_reference (\fBglobus_handle_table_t\fP * handle_table, \fBglobus_handle_t\fP handle)"

.PP
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\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP The table that the handle was created in\&. 
.br
\fIhandle\fP 
.br
 The handle to a datum to decrement the reference count for\&.
.RE
.PP
\fBReturns\fP
.RS 4
The \fBglobus_handle_table_decrement_reference()\fP function returns a boolean value indicating whether the handle still references a valid datum\&. 
.RE
.PP

.SS "int globus_handle_table_destroy (\fBglobus_handle_table_t\fP * handle_table)"

.PP
Destroy a handle table\&. Destroy a handle table and call the destructor for all objects associated with it\&. 
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP Pointer to the handle table to destroy 
.RE
.PP

.SS "\fBglobus_bool_t\fP globus_handle_table_increment_reference (\fBglobus_handle_table_t\fP * handle_table, \fBglobus_handle_t\fP handle)"

.PP
Add a reference to a handle table entry\&. 
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP The table that the handle was created in\&. 
.br
\fIhandle\fP 
.br
 The handle to a datum to increment the reference count for\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The \fBglobus_handle_table_increment_reference()\fP function returns a boolean value indicating whether the handle still references a valid datum\&. 
.RE
.PP

.SS "\fBglobus_bool_t\fP globus_handle_table_increment_reference_by (\fBglobus_handle_table_t\fP * handle_table, \fBglobus_handle_t\fP handle, unsigned int inc)"

.PP
Increment the reference count for handle\&. 
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP The table that the handle was created in\&. 
.br
\fIhandle\fP 
.br
 The handle to a datum to increment the reference count for\&. 
.br
\fIinc\fP The number of references to add the handle\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The \fBglobus_handle_table_increment_reference_by()\fP function returns a boolean value indicating whether the handle still references a valid datum\&. 
.RE
.PP

.SS "int globus_handle_table_init (\fBglobus_handle_table_t\fP * handle_table, \fBglobus_handle_destructor_t\fP destructor)"
Initialize a table of unique reference counted handles\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP the table of unique handles we want to use\&. 
.br
\fIdestructor\fP 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\&. 
.RE
.PP

.SS "\fBglobus_handle_t\fP globus_handle_table_insert (\fBglobus_handle_table_t\fP * handle_table, void * value, int initial_refs)"
Insert a datum into a handle table
.PP
Insert a value into the handle table, and return a unique handle to it\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP Handle table to add the value to 
.br
\fIvalue\fP The value to insert into the table 
.br
\fIinitial_refs\fP The initial reference count of this value in the table
.RE
.PP
\fBReturns\fP
.RS 4
The \fBglobus_handle_table_insert()\fP function returns a unique handle to value\&. 
.RE
.PP

.SS "void * globus_handle_table_lookup (\fBglobus_handle_table_t\fP * handle_table, \fBglobus_handle_t\fP handle)"

.PP
Resolve a handle its datum\&. 
.PP
\fBParameters\fP
.RS 4
\fIhandle_table\fP The table that the handle was created in\&. 
.br
\fIhandle\fP 
.br
 The handle to a datum to resolve 
.RE
.PP
\fBReturns\fP
.RS 4
The \fBglobus_handle_table_lookup()\fP function returns the datum associated with the handle in the handle table, or NULL if the handle does not reference valid data\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_common from the source code\&.