Handles(3tclx)

💖 Handles — dynamic, handle addressable tables 💖

ok so this is Handles(3tclx), bestie. it's the TclX handle facility and honestly it's giving backstage pass to your data structures. come sit with me, we're gonna go through it line by line, no skips, no cap.

---

✨ NAME ✨

Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit, Tcl_HandleTblRelease, Tcl_HandleTblUseCount, Tcl_HandleWalk, Tcl_HandleXlate — dynamic, handle addressable tables. yes that's seven functions in a trench coat. they all live here. 🫶

---

🌸 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 🦋

okay so here's the whole vibe. the Tcl handle facility is a way to manage table entries that might get referenced by a textual handle from Tcl code. it exists for applications that need to create data structures in one command, hand back a reference (i.e. a pointer) to that specific data structure, and then access that same data structure from other commands. the classic example? file handles. iconic behavior honestly.

a handle is made of two parts: a base name, which is some unique, meaningful name like file, plus a numeric value tacked onto the end of it (so like file3). periodt.

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.

⚠️ now listen, this part matters: the tables get expanded when needed, which means you should not keep pointers to entries — they will become invalid when the table is expanded. 😭

if your table entries are large, or you genuinely need to keep pointers to the entries, then the entries should be allocated separately and the pointers kept in the handle table. problem solved, slay.

also there's a use count kept on the table. that use count is there to determine when a table shared by multiple commands should be released. team effort energy. 💅

---

🎀 Tcl_HandleTblInit

create and initialize a Tcl dynamic handle table. the use count on the table gets set to one. fresh start, main character energy.

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. and here's the cute part — amount may be zero to just retrieve the use count. no change, just vibes. 👑

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. that's it. that's the whole job. bye bestie. 👋

Parameters:

• headerPtr — pointer to the table header.

---

✨ Tcl_HandleAlloc

allocate an entry and associate a handle with it. matchmaker behavior fr fr.

Parameters:

• headerPtr — a pointer to the table header.
• handlePtr — buffer to return handle in. it must be big enough to hold the name. no shortcuts here, she needs room. 🙈

Returns:

a pointer to the allocated entry (user part).

---

💜 Tcl_HandleXlate

translate a handle to an entry pointer. it's the translator, the go-between, the one who speaks both languages. 🌈

Parameters:

• interp — a 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.

🚨 important: entries may be deallocated during a walk, but they should not be allocated. read that again, bestie.

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. do not forget this. do not. 😤

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. and heads up — the Tcl_HandleWalk must have succeeded. no pretending. the key has to be legit. 💅

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. release her, she served her purpose. 💖

Parameters:

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

---

that's the whole page, babe. every function, every parameter, every return value, every warning — nothing skipped, because you deserve the full picture. go build something iconic with it. ✨

signing off — this is Tcl, from the Handles(3tclx) manual page, and yeah it's the real deal. mwah. 💋