Tcl_Preserve(3)

💖 Tcl_Preserve — the manual, but make it make sense 💖

okay bestie, this is a page from the Tcl Library Procedures manual, and it's about Tcl_Preserve, Tcl_Release, and Tcl_EventuallyFree. It's giving "don't you dare free my memory while I'm still using it" energy, and honestly? iconic. 🫶

---

✨ NAME ✨

Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree — the trio that stops you from freeing storage while it's still being used. no cap.

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_Preserve(clientData)

Tcl_Release(clientData)

Tcl_EventuallyFree(clientData, freeProc)

---

🎀 ARGUMENTS 🎀

• void *clientData (in) — the token that describes the structure you're gonna free or reallocate. usually it's just a pointer to the memory for the structure. it's the little name tag for your object. 🏷️
• Tcl_FreeProc *freeProc (in) — the procedure you invoke to free clientData. that's the one who actually does the deed.

---

💅 DESCRIPTION 💅

so these three procedures help you implement a simple reference count mechanism for managing storage. they were designed to solve a problem that's all about widget deletion, but bestie, they're useful in a whole bunch of other situations too. 💖

here's the situation. when a widget gets deleted, its widget record — that's the structure holding all the info specific to that widget — has to be returned to the storage allocator. but plot twist: it's totally possible that the widget record is still in active use by one of the procedures sitting on the stack at the exact moment of deletion. 😭

and like, this happens for real. for example: if the command associated with a button widget causes the button to be destroyed. so an X event causes an event-handling C procedure in the button to be invoked, which causes the button's associated Tcl command to be executed, which causes the button to be deleted, which causes the button's widget record to be de-allocated. 😵‍💫

but unfortunately — and this is the messy part — when the Tcl command returns, the button's event-handling procedure is gonna need to reference the button's widget record. so because of that, the widget record must not be freed as part of the deletion. it has to be retained until the event-handling procedure has finished with it. in other situations where the widget is deleted, it may be possible to free the widget record immediately. it's giving "it depends" 💀

so Tcl_Preserve and Tcl_Release implement short-term reference counts for their clientData argument. the clientData argument identifies an object and usually consists of the address of a structure. the reference counts guarantee that an object will not be freed until each call to Tcl_Preserve for the object has been matched by calls to Tcl_Release. and there may be any number of unmatched Tcl_Preserve calls in effect at once. stack 'em up, girl. 👑

now Tcl_EventuallyFree is the one you invoke to free up its clientData argument. here's what it does: it checks to see if there are unmatched Tcl_Preserve calls for the object.

• if there are not — then Tcl_EventuallyFree calls freeProc immediately. done, slay. ✨
• if there are — then Tcl_EventuallyFree records the fact that clientData needs eventually to be freed. and when all calls to Tcl_Preserve have been matched with calls to Tcl_Release, then freeProc will be called by Tcl_Release to do the cleanup. it's the group project that actually gets finished. 🫶

all the work of freeing the object is carried out by freeProc. and freeProc must have arguments and result that match the type Tcl_FreeProc:

typedef void Tcl_FreeProc(
        void *blockPtr);

the blockPtr argument to freeProc will be the same as the clientData argument to Tcl_EventuallyFree. same girl, different name tag. 💅

when the clientData argument to Tcl_EventuallyFree refers to storage allocated and returned by a prior call to Tcl_Alloc or another function of the Tcl library, then the freeProc argument should be given the special value of TCL_DYNAMIC. don't forget it, bestie, that's the shortcut. 🎀

this mechanism can be used to solve the problem described above by placing Tcl_Preserve and Tcl_Release calls around actions that may cause undesired storage re-allocation.

but real talk — the mechanism is intended only for short-term use (i.e. while procedures are pending on the stack). it will not work efficiently as a mechanism for long-term reference counts. so don't get any ideas. 🙈

and the implementation does not depend in any way on the internal structure of the objects being freed — it keeps the reference counts in a separate structure. main character energy: minding its own business, keeping receipts elsewhere. 📝

---

👀 SEE ALSO 👀

• Tcl_Interp
• Tcl_Alloc

---

🔑 KEYWORDS 🔑

free, reference count, storage

---

and that's the whole vibe check, bestie — this page came straight out of the Tcl manual, version 7.5, dated Tcl_Preserve(3). go forth and preserve your storage responsibly. periodt. 💜✨