---
name: "globus_handle_table"
section: "3"
platform: "linux"
package: "libglobus-common-doc"
version: "18.14-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/globus_handle_table"
---

# globus\_handle\_table(3)

Handle Table for Reference Counting Data - Handle Table for Reference Counting Data.

## NAME

globus\_handle\_table - Handle Table for Reference Counting Data

 \- Handle Table for Reference Counting Data.

## SYNOPSIS

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

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

## Author

Generated automatically by Doxygen for globus\_common from the source code.