.TH "Handle Table for Reference Counting Data" 3 "Sat Nov 8 2014" "Version 15.26" "globus_common" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Handle Table for Reference Counting Data \- 
.SS "Macros"

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

.in +1c
.ti -1c
.RI "typedef struct 
.br
globus_l_handle_table_s * \fBglobus_handle_table_t\fP"
.br
.RI "\fIHandle table abstract type\&. \fP"
.ti -1c
.RI "typedef int \fBglobus_handle_t\fP"
.br
.RI "\fIHandle abstract type\&. \fP"
.ti -1c
.RI "typedef void(* \fBglobus_handle_destructor_t\fP )(void *datum)"
.br
.RI "\fIHandle datum destructor\&. \fP"
.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 "\fIDestroy a handle table\&. \fP"
.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 "\fIIncrement the reference count for handle\&. \fP"
.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 "\fIAdd a reference to a handle table entry\&. \fP"
.ti -1c
.RI "void * \fBglobus_handle_table_lookup\fP (\fBglobus_handle_table_t\fP *handle_table, \fBglobus_handle_t\fP handle)"
.br
.RI "\fIResolve a handle its datum\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
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 "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\fPhandle)"

.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 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\fPhandle, unsigned intinc)"

.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 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\fPdestructor)"
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, intinitial_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\fPhandle)"

.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 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\&.