Tcl_CreateInterp(3)

🌸 NAME 🌸

Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted — bestie, this is the create and delete Tcl command interpreters page. Your whole interpreter lifecycle, right here, in the Tcl Library Procedures manual (that's Tcl_CreateInterp(3), iykyk 💅).

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_Interp *
Tcl_CreateInterp()

Tcl_DeleteInterp(interp)

int
Tcl_InterpDeleted(interp)

int
Tcl_InterpActive(interp)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — Token for the interpreter you're destroying or querying. That's the whole cast list, one (1) argument, she's low maintenance 🫶

---

🦋 DESCRIPTION 🦋

Tcl_CreateInterp creates a brand-new interpreter structure and hands you back a token for it. That token? Required. You'll need it for calls to most other Tcl procedures, like Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp — she's the VIP pass, fr fr.

Real talk though: the token returned by Tcl_CreateInterp may only be passed to Tcl routines 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. No sharing, no passing her around the group chat 😭

The new interpreter comes pre-loaded with the built-in Tcl commands and with standard variables like tcl_platform and env. Want more commands in there? Call Tcl_CreateCommand. Want more variables? Call Tcl_SetVar. Slay, customizable 👑

Tcl_DeleteInterp marks an interpreter as deleted — note the word marks, because she doesn't actually go anywhere yet. The interpreter will eventually be deleted when all calls to Tcl_Preserve for it have been matched by calls to Tcl_Release. At that time, everything associated with her gets deleted: variables, procedures, and application-specific command bindings, all of it. Gone. 💀

After Tcl_DeleteInterp returns, any attempt to use Tcl_Eval on the interpreter will fail and return TCL_ERROR. But — and this is the good news — after the call to Tcl_DeleteInterp it is safe to examine the interpreter's result, query or set the values of variables, define, undefine or retrieve procedures, and examine the runtime evaluation stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT, for details 🫶

Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with interp as its argument. That nonzero means the interpreter will eventually be deleted, when the last call to Tcl_Preserve for it is matched by a call to Tcl_Release. And if nonzero is returned? Further calls to Tcl_Eval in this interpreter will return TCL_ERROR. So like, that's your vibe check right there.

Why do you care? Because Tcl_InterpDeleted is useful in deletion callbacks to tell the difference between only the memory the callback is responsible for being deleted and the whole interpreter being deleted. In the former case the callback may recreate the data being deleted — but bestie, that would lead to an infinite loop if the interpreter were being deleted. So check first. Always check 🙈

Tcl_InterpActive is your "is anything happening in here right now" function. It's useful for determining whether there is any execution of scripts ongoing in an interpreter, which is a genuinely useful piece of information when Tcl is embedded in a garbage-collected environment and it becomes necessary to determine whether the interpreter is a candidate for deletion. The function returns a true value if the interpreter has at least one active execution running inside it, and a false value otherwise. Simple. Iconic. ✨

---

🧠 INTERPRETERS AND MEMORY MANAGEMENT 🧠

Tcl_DeleteInterp can be called at any time on an interpreter that may be used by nested evaluations and C code in various extensions. Tcl implements a simple mechanism that lets callers use interpreters without worrying about the interpreter being deleted in a nested call, and without requiring special code to protect the interpreter, in most cases. This mechanism ensures that nested uses of an interpreter can safely continue using it even after Tcl_DeleteInterp is called. Protected and unbothered 🛡️

The mechanism relies on matching up calls to Tcl_Preserve with calls to Tcl_Release. If Tcl_DeleteInterp has been called, only when the last call to Tcl_Preserve is matched by a call to Tcl_Release will the interpreter be freed. See the manual entry for Tcl_Preserve for a description of these functions.

The rules for when the user of an interpreter must call Tcl_Preserve and Tcl_Release are simple:

🌈 Interpreters Passed As Arguments

Functions that are passed an interpreter as an argument can safely use the interpreter without any special protection. So when you write an extension consisting of new Tcl commands, no special code is needed to protect interpreters received as arguments. This covers the majority of all uses. Easy mode, no cap.

🌈 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, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter. Remember: it is unsafe to use the interpreter once Tcl_Release has been called. To ensure that the interpreter is properly deleted when it is no longer needed, call Tcl_InterpDeleted to test if some other code already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp before calling Tcl_Release in your own code. Order matters, bestie, don't freestyle this 💅

🌈 Retrieving An Interpreter From A Data Structure

When an interpreter is retrieved from a data structure (e.g. the client data of a callback) for use in one of the evaluation functions (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_EvalObjv, etc.) or variable access functions (Tcl_SetVar, Tcl_GetVar, Tcl_SetVar2Ex, etc.), a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter; it is unsafe to reuse the interpreter once Tcl_Release has been called.

If an interpreter is stored inside a callback data structure, an appropriate deletion cleanup mechanism should be set up by the code that creates the data structure so that the interpreter is removed from the data structure (e.g. by setting the field to NULL) when the interpreter is deleted.

Otherwise, you may be using an interpreter that has been freed and whose memory may already have been reused. That's not a vibe. That's a crash. 😭

All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that their code also properly protects any additional interpreters used, as described above. Do your part, protect your interpreters 🫶

Note that the protection mechanisms do not work well with conventional garbage collection systems. When in such a managed environment, Tcl_InterpActive should be used to determine when an interpreter is a candidate for deletion due to inactivity. That's literally what she's for, queen 👑

---

🔍 SEE ALSO 🔍

• Tcl_Preserve(3)
• Tcl_Release(3)

---

🔑 KEYWORDS 🔑

command, create, delete, interpreter

---

And that's the whole page, bestie — this one came straight out of the Tcl manual, version 7.5, with Tcl_CreateInterp(3) stamped right there on the cover like a little crown 👑 go protect your interpreters, mwah 💖✨