Tcl_Cancel(3)

💅 Tcl_Cancel — the tea on canceling Tcl scripts 🛑

okay so bestie, this is a page from the Tcl Library Procedures manual, and it's literally all about telling a running script to sit down and stop. two functions, one mission: cancel. let's get into it 🫶

---

✨ NAME ✨

Tcl_CancelEval, Tcl_Canceled — cancel Tcl scripts. that's it, that's the whole vibe 🎀

---

🌸 SYNOPSIS 🌸

#include <tcl.h>
int
Tcl_CancelEval(interp, resultObjPtr, clientData, flags)

int
Tcl_Canceled(interp, flags)

---

🦋 ARGUMENTS 🦋

• Tcl_Interp *interp (in) — the interpreter where we're canceling the script. it's giving "the scene of the crime" ✨
• Tcl_Obj *resultObjPtr (in) — the error message you want to use for the cancellation, or NULL if you'd rather just use a default message (no thoughts, head empty, default slay). lowkey important: if this is not NULL, this object will have its reference count decremented before Tcl_CancelEval returns. yes, really, it's a whole thing — more on that below 👀
• int flags (in) — an OR'ed combination of flag bits that specify extra options. for Tcl_CancelEval, only TCL_CANCEL_UNWIND is currently supported. for Tcl_Canceled, only TCL_LEAVE_ERR_MSG and TCL_CANCEL_UNWIND are currently supported. so like, pick from the menu, don't freestyle 🧚
• void *clientData (in) — currently reserved for future use. set it to NULL. periodt 💅

---

👑 DESCRIPTION 👑

Tcl_CancelEval cancels or unwinds the script in progress soon after the next invocation of asynchronous handlers, and it makes TCL_ERROR the return code for that script. the way it's thread-safe and can be called from any thread in the process? iconic. truly main character energy 🌈

Tcl_Canceled checks if the script in progress has been canceled and returns TCL_ERROR if it has. otherwise, TCL_OK is returned. extensions can use this function to check whether they should abort a long running command — like a little vibe check mid-command, fr fr. this function is thread sensitive though, so it may only be called from the thread the interpreter was created in. don't try it anywhere else bestie, that's not your lane 💀

🎀 FLAG BITS 🎀

any OR'ed combination of the following values may be used for the flags argument to procedures such as Tcl_CancelEval:

• TCL_CANCEL_UNWIND — this flag is used by both Tcl_CancelEval and Tcl_Canceled. for Tcl_CancelEval: if this flag is set, the script in progress is canceled and the evaluation stack for the interpreter is unwound (we're going all the way down, no half measures 🌀). for Tcl_Canceled: if this flag is set, the script in progress is considered to be canceled only if the evaluation stack for the interpreter is being unwound. so it's a picky lil flag, iykyk.
• TCL_LEAVE_ERR_MSG — this flag is only used by Tcl_Canceled; it is ignored by other procedures (they literally do not care 🙈). if an error is returned and this bit is set in flags, then an error message will be left in the interpreter's result, where it can be retrieved with Tcl_GetObjResult or Tcl_GetStringResult. if this flag bit is not set, then no error message is left and the interpreter's result will not be modified. so either you get the message or you get silence, no in-between ✨

---

💖 REFERENCE COUNT MANAGEMENT 💖

okay this is the part where you pay attention, bestie, because refcounts are where dreams go to die 😭

Tcl_CancelEval always decrements the reference count of its resultObjPtr argument (if that is non-NULL). it is expected to be usually called with an object with zero reference count. if the object is shared with some other location (including the Tcl evaluation stack), it should have its reference count incremented before calling this function.

so like. if you're sharing that object around, bump the refcount first. otherwise you're gonna have a bad time and the crash will be entirely your fault 💀

---

🌟 SEE ALSO 🌟

• interp(n)
• Tcl_Eval(3)

---

🍓 KEYWORDS 🍓

cancel, unwind

---

and that's the whole page, no cap. go forth and cancel responsibly, bestie 🫶

this was brought to you by the Tcl girls, version 8.6, on the Tcl_Cancel(3) page — mwah 💋🎀✨