Handles(3tcl)

✨ NAME ✨

Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit, Tcl_HandleTblRelease, Tcl_HandleTblUseCount, Tcl_HandleWalk, Tcl_HandleXlate — Dynamic, handle addressable tables. 💅

bestie this is the Handles(3tcl) manual page, and it's giving "let's manage table entries with textual handles" energy. 🫶

---

🦋 SYNOPSIS 🦋

#include <tclExtend.h>

void_pt
Tcl_HandleTblInit (const char *handleBase,
                   int         entrySize,
                   int         initEntries);

int
Tcl_HandleTblUseCount (void_pt  headerPtr,
                       int      amount);

void
Tcl_HandleTblRelease (void_pt headerPtr);

void_pt
Tcl_HandleAlloc (void_pt   headerPtr,
                 char     *handlePtr);

void_pt
Tcl_HandleXlate (Tcl_Interp *interp,
                 void_pt     headerPtr,
                 const char *handle);

void_pt
Tcl_HandleWalk (void_pt   headerPtr,
                int      *walkKeyPtr);

void
Tcl_WalkKeyToHandle (void_pt   headerPtr,
                     int       walkKey,
                     char     *handlePtr);

void
Tcl_HandleFree (void_pt headerPtr,
                void_pt entryPtr);

---

💖 DESCRIPTION 💖

The Tcl handle facility is literally a way to manage table entries that can be referenced by a textual handle from Tcl code. It's for apps that need to create data structures in one command, return a reference (i.e. pointer) to that particular data structure, and then access that data structure in other commands. An example application is file handles. 🗂️

A handle is a base name — some unique, meaningful name like file — plus a numeric value appended to it (e.g. file3). The handle facility is designed to give you a standard mechanism for building Tcl commands that allocate and access table entries based on an entry index. The tables expand when needed, so do not keep pointers to entries, bestie — they become invalid when the table expands. 😭 If the table entries are large or you must keep pointers to the entries, then the entries should be allocated separately and pointers kept in the handle table. A use count is kept on the table. This use count is intended to determine when a table shared by multiple commands is to be released. 👑

---

🎀 Tcl_HandleTblInit 🎀

Create and initialize a Tcl dynamic handle table. The use count on the table is set to one. ✨

Parameters:

• handleBase — the base name of the handle; the handle will be returned in the form "baseNN", where NN is the table entry number.
• entrySize — the size of an entry, in bytes.
• initEntries — initial size of the table, in entries.

Returns:

A pointer to the table header. 👑

---

🦋 Tcl_HandleTblUseCount 🦋

Alter the handle table use count by the specified amount, which can be positive or negative. Amount may be zero to retrieve the use count. 🔢

Parameters:

• headerPtr — pointer to the table header.
• amount — the amount to alter the use count by.

Returns:

The resulting use count.

---

🌸 Tcl_HandleTblRelease 🌸

Decrement the use count on a Tcl dynamic handle table. If the count goes to zero or negative, then release the table. 🫶

Parameters:

• headerPtr — pointer to the table header.

---

💅 Tcl_HandleAlloc 💅

Allocate an entry and associate a handle with it.

Parameters:

• headerPtr — a pointer to the table header.
• handlePtr — buffer to return handle in. It must be big enough to hold the name.

Returns:

A pointer to the allocated entry (user part). 🎀

---

🔥 Tcl_HandleXlate 🔥

Translate a handle to an entry pointer.

Parameters:

• interp — an error message may be returned in result.
• headerPtr — a pointer to the table header.
• handle — the handle assigned to the entry.

Returns:

A pointer to the entry, or NULL if an error occurred. 🚫

---

🧚 Tcl_HandleWalk 🧚

Walk through and find every allocated entry in a table. Entries may be deallocated during a walk, but should not be allocated. 🚶‍♀️

Parameters:

• headerPtr — a pointer to the table header.
• walkKeyPtr — pointer to a variable to use to keep track of the place in the table. The variable should be initialized to -1 before the first call.

Returns:

A pointer to the next allocated entry, or NULL if there are not more.

---

🍓 Tcl_WalkKeyToHandle 🍓

Convert a walk key, as returned from a call to Tcl_HandleWalk, into a handle. The Tcl_HandleWalk must have succeeded. 🔑

Parameters:

• headerPtr — a pointer to the table header.
• walkKey — the walk key.
• handlePtr — buffer to return handle in. It must be big enough to hold the name.

---

💜 Tcl_HandleFree 💜

Frees a handle table entry. 🗑️

Parameters:

• headerPtr — a pointer to the table header.
• entryPtr — entry to free.

---

source: Tcl — section: Handles(3tcl). that's the whole page, bestie. no cap, go build something iconic. 💅✨🫶