Tcl_Cancel(3tcl)

Tcl_Cancel — the manual page, bestie edition 💅

okay so this is straight out of the Tcl Library Procedures manual, and it's literally all about canceling Tcl scripts. two functions, one mission: make the script STOP. 🛑

---

✨ 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 "which one of y'all is getting stopped" energy.
• Tcl_Obj *resultObjPtr (in) — the error message to use in the cancellation, or NULL if you want a default message instead. and heads up: if it's not NULL, this object gets its reference count decremented before Tcl_CancelEval returns. so keep an eye on it, fr.
• int flags (in) — an OR'ed combo of flag bits for 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.
• void *clientData (in) — rn this is reserved for future use, so just set it to NULL and move on. it's not doing anything yet, no cap. 🙈

---

🦋 DESCRIPTION 🦋

Tcl_CancelEval cancels or unwinds whatever script is in progress, and it does it soon after the next invocation of asynchronous handlers — which makes TCL_ERROR the return code for that script. and the iconic part? this function is thread-safe, so you can call it from any thread in the process. main character energy across every thread. 👑

Tcl_Canceled checks whether the script in progress has been canceled, and returns TCL_ERROR if it has. otherwise you get TCL_OK back. extensions can use this to check whether they should bail out of a long running command — lowkey essential if you don't want your command just sitting there forever. but this one is thread sensitive, and it may only be called from the thread the interpreter was created in. respect the thread, bestie. 🧵

⭐ FLAG BITS ⭐

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

• TCL_CANCEL_UNWIND — this flag is used by 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. for Tcl_Canceled, if this flag is set, the script in progress is considered canceled only if the evaluation stack for the interpreter is being unwound. context matters, periodt. ✨
• TCL_LEAVE_ERR_MSG — only Tcl_Canceled uses this one; every other procedure ignores it. if an error is returned and this bit is set in flags, then an error message gets left in the interpreter's result, where you can retrieve it 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 it's the "do you want the receipts or not" flag. 🧾

---

🫶 REFERENCE COUNT MANAGEMENT 🫶

Tcl_CancelEval always decrements the reference count of its resultObjPtr argument (if that's non-NULL). it's expected to usually be called with an object that has a zero reference count. but if the object is shared with some other location (including the Tcl evaluation stack), it should have its reference count incremented before you call this function. this is the part where you double-check before you hit go, i promise. 💀

---

🌈 SEE ALSO 🌈

• interp(3tcl)
• Tcl_Eval(3tcl)

---

💜 KEYWORDS 💜

cancel, unwind

---

and that's the whole page, bestie. this one's from Tcl version 8.6, filed under Tcl_Cancel(3tcl) — go forth and cancel responsibly. slay. 💅✨🦋