Tcl_CreateInterp(3tcl)

✨ Tcl_CreateInterp — create and delete Tcl command interpreters ✨

ok so bestie, welcome to the Tcl Library Procedures section 💖 this one is about Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, and Tcl_InterpDeleted — aka making interpreters and (respectfully) unmaking them. it's giving birth-and-death but for data structures. no cap. 🦋

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_Interp *
Tcl_CreateInterp()

Tcl_DeleteInterp(interp)

int
Tcl_InterpDeleted(interp)

int
Tcl_InterpActive(interp)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the token for the interpreter you're destroying or interrogating, queen. it's the thing getting deleted or queried. 🫶

---

💅 DESCRIPTION 💅

okay so Tcl_CreateInterp creates a brand new interpreter structure and hands you back a token for it. that token is literally required for basically everything else — Tcl_CreateCommand, Tcl_Eval, Tcl_DeleteInterp, the whole squad. ✨

but here's the tea: the token from Tcl_CreateInterp may only be passed to Tcl routines that get called from the same thread as the original Tcl_CreateInterp call. it is not safe for multiple threads to pass the same token to Tcl's routines. periodt. 🚫🧵

the new interpreter comes pre-loaded with the built-in Tcl commands and the standard variables like tcl_platform and env — like it showed up to the function fully dressed 👑. want more commands? call Tcl_CreateCommand. want more variables? call Tcl_SetVar. easy.

Tcl_DeleteInterp marks an interpreter as deleted — but it's not an instant death, it's a scheduled one, main character exit energy 💀. the interpreter will eventually be deleted once all calls to Tcl_Preserve for it have been matched by calls to Tcl_Release. at that moment, all the resources tied to it get deleted too — variables, procedures, application-specific command bindings, all of it, gone. 🧚

after Tcl_DeleteInterp returns, any attempt to use Tcl_Eval on that interpreter will fail and return TCL_ERROR. but — and this is the plot twist — after the call it is safe to examine the interpreter's result, query or set variable values, define/undefine/retrieve procedures, and examine the runtime evaluation stack. check the INTERPRETERS AND MEMORY MANAGEMENT section below for the deets. 💜

Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with interp as its argument. that nonzero is basically saying "yeah this one's on its way out, it'll be deleted when the last Tcl_Preserve call for it is matched by a Tcl_Release". and if you get nonzero back, further calls to Tcl_Eval in that interpreter will return TCL_ERROR. 💥

Tcl_InterpDeleted is so useful in deletion callbacks, because it lets you tell the difference between "only the memory I'm responsible for is being deleted" and "the whole entire interpreter is being deleted". in the first case, your callback could legitimately recreate the data being deleted — but if you did that while the whole interpreter was being deleted, you'd be in an infinite loop, and nobody wants that 🙈.

Tcl_InterpActive is the vibe check you need when you want to know if any script execution is currently going on inside an interpreter 🏃♀️. that's genuinely useful info when Tcl is embedded in a garbage-collected environment and you need to figure out whether an interpreter is a candidate for deletion. it returns a true value if the interpreter has at least one active execution running inside it, and a false value otherwise. slay. ✅

---

🌈 INTERPRETERS AND MEMORY MANAGEMENT 🌈

Tcl_DeleteInterp can be called at literally any time on an interpreter that might be used by nested evaluations and C code across all kinds of extensions. Tcl runs a simple mechanism that lets callers use interpreters without stressing about the interpreter getting deleted in a nested call — and in most cases, without needing any special protection code at all. 🛡️ this mechanism guarantees that nested uses of an interpreter can keep safely using it even after Tcl_DeleteInterp is called. iconic behaviour, honestly.

the whole thing relies on matching up calls to Tcl_Preserve with calls to Tcl_Release. if Tcl_DeleteInterp has been called, the interpreter only gets freed when the last Tcl_Preserve call is matched by a Tcl_Release call. for a full description of these functions, go read the Tcl_Preserve manual entry. 📖

the rules for when you, the user of an interpreter, have to call Tcl_Preserve and Tcl_Release? lowkey simple:

🦋 Interpreters Passed As Arguments

functions that get an interpreter as an argument can safely use that interpreter with zero special protection. so when you're writing an extension made of new Tcl commands, no special code is needed to protect interpreters you receive as arguments. this covers the majority of all uses — the standard case, the everyday fit, the go-to lewk. 👑

🍓 Interpreter Creation And Deletion

when a new interpreter is created and used in a call to Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, you should wrap a pair of Tcl_Preserve and Tcl_Release calls around all uses of the interpreter. 🫶

remember: it is unsafe to use the interpreter once Tcl_Release has been called. no take-backs, no reusing, that's the rule. ⚠️

and to make sure the interpreter actually gets properly deleted when it's no longer needed, call Tcl_InterpDeleted to test whether some other code already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp before calling Tcl_Release in your own code. 🌸

🧚 Retrieving An Interpreter From A Data Structure

when an interpreter gets retrieved from a data structure (like, say, the client data of a callback) for use in one of the evaluation functions (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_EvalObjv, etc.) or the variable access functions (Tcl_SetVar, Tcl_GetVar, Tcl_SetVar2Ex, etc.), wrap a pair of Tcl_Preserve and Tcl_Release calls around all uses of the interpreter. it is unsafe to reuse the interpreter once Tcl_Release has been called — same energy as above, fr fr. 💫

if an interpreter is stored inside a callback data structure, the code that creates that data structure should set up an appropriate deletion cleanup mechanism, so the interpreter gets removed from the structure (e.g. by setting the field to NULL) when the interpreter is deleted. otherwise? you may be using an interpreter that has already been freed, whose memory may already have been reused. 💀 that's the nightmare scenario, bestie. don't do that.

all uses of interpreters in Tcl and Tk have already been protected. ✅ extension writers should make sure their code also properly protects any additional interpreters used, following the rules above. do your part. 💅

note: the protection mechanisms do not work well with conventional garbage collection systems. when you're in such a managed environment, use Tcl_InterpActive to determine when an interpreter is a candidate for deletion due to inactivity. 🧠

---

👀 SEE ALSO 👀

• Tcl_Preserve(3tcl)
• Tcl_Release(3tcl)

---

🔥 KEYWORDS 🔥

command, create, delete, interpreter

---

okay that's the whole page, you're officially fluent in interpreter lifecycles 🎀✨ and one last thing: this whole thing lives in the Tcl manual, version 7.5, dated all the way back at 7.5 — shoutout to the Tcl crew for the lore, mwah 💖👑🦋