globus_handle_table(3)

🌸 globus_handle_table 🌸

okay bestie, welcome to globus_handle_table(3) — that's a manual page from the Library Functions Manual, and it's literally all about a handle table that does reference counting for your data. we're gonna go through the whole thing together, no skips, no vibes lost 💅

---

✨ NAME ✨

globus_handle_table — Handle Table for Reference Counting Data

• Handle Table for Reference Counting Data.

yes it says it twice, that's just how it is, iconic honestly 🫶

---

🦋 SYNOPSIS 🦋

Macros

#define GLOBUS_NULL_HANDLE

Typedefs

typedef struct globus_l_handle_table_s * globus_handle_table_t
typedef int globus_handle_t
typedef void(* globus_handle_destructor_t) (void *datum)

• globus_handle_table_t — Handle table abstract type.
• globus_handle_t — Handle abstract type.
• globus_handle_destructor_t — 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)
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)
globus_bool_t globus_handle_table_decrement_reference
    (globus_handle_table_t *handle_table, globus_handle_t handle)
globus_bool_t globus_handle_table_increment_reference
    (globus_handle_table_t *handle_table, globus_handle_t handle)
void * globus_handle_table_lookup (globus_handle_table_t *handle_table,
    globus_handle_t handle)

• globus_handle_table_destroy() — Destroy a handle table.
• globus_handle_table_increment_reference_by() — Increment the reference count for handle.
• globus_handle_table_decrement_reference() — Remove a reference to a handle.
• globus_handle_table_increment_reference() — Add a reference to a handle table entry.
• globus_handle_table_lookup() — Resolve a handle its datum.

---

💖 DETAILED DESCRIPTION 💖

Handle Table for Reference Counting Data.

okay so here's the tea 🍓 — the globus_handle_table_t abstraction gives you a reference-counting handle table that automatically frees your data when there are no more references to it. no manual cleanup drama, she handles it.

Every single datum chillin' in the globus_handle_table_t container has a count attached to it, and that count can go up and down — either in single steps or by an increment. as long as a handle has any references pointing at it, globus_handle_table_lookup() will hand you back the datum associated with that handle. and if it doesn't? you get NULL. that's it, that's the whole system 💀

and here's a lil detail you don't wanna miss: the value of a globus_handle_t is not reused until INT_MAX data have been inserted into the handle table. so like, no handle identity theft happening here, periodt.

---

🎀 MACRO DEFINITION DOCUMENTATION 🎀

#define GLOBUS_NULL_HANDLE

Invalid handle value

she's the placeholder, the "nothing here" girlie, the invalid one 🙈

---

🌈 TYPEDEF DOCUMENTATION 🌈

typedef void(* globus_handle_destructor_t) (void *datum)

Handle datum destructor.

Parameters

• datum — Datum to destroy

this is the lil callback that shows up when your datum's time has come. it takes a void *datum and that's the thing getting destroyed 🧚

---

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

so you're taking one reference away. and if that was the last one? boom, destructor gets called, she's gone 💅

---

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

nuclear option, but make it polite — everything in the table gets its destructor called on the way out 🔥

---

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.

one reference, added, just like that ✨

---

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.

same energy as above but you're adding multiple references at once because you're extra like that 💖

---

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.

this is step one bestie, you gotta init before you do literally anything else 🌱

---

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.

you put a thing in, you get a unique handle back. no dupes, no copycats, no cap 🫶

---

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.

your main character moment — you hand over the handle, you get the datum. unless it's not valid, in which case: NULL, sorry babe 😭

---

💜 AUTHOR 💜

Generated automatically by Doxygen for globus_common from the source code.

---

and that's the whole page, bestie!! 🌈 this was globus_common, Version 18.15, and the page is globus_handle_table(3) — go forth and reference count responsibly, mwah 💋🎀