Tcl_BackgroundError(3)

💖 NAME 💖

Tcl_BackgroundException, Tcl_BackgroundError — bestie, these two are how you spill the tea that a Tcl exception happened during background processing. Like, it went down while nobody was looking and now you gotta tell somebody.

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_BackgroundException(interp, code)

Tcl_BackgroundError(interp)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter where the whole exception situation went down.
• int code (in) — the exceptional return code you're reporting. The receipts, basically.

---

🌸 DESCRIPTION 🌸

So here's the vibe. You call this procedure when a Tcl exception happens — and by exception we mean any return code that isn't TCL_OK — during what we call “background processing”, like running an event handler. When that happens, the condition gets reported to Tcl, or to a widget, or to some other C code, and usually that code has literally no obvious way to tell the user about it. Awkward. 😭

So in those cases the code calls Tcl_BackgroundException, handing over an interp argument that says which interpreter the exception happened in, plus a code argument holding the return code value of the exception. The state of the interpreter gets captured and saved — and yes, that includes any error message sitting in the interpreter result, and the values of any entries in the return options dictionary. All of it, saved. 🫶

Then Tcl_BackgroundException arranges for the event loop to invoke, at some later time, the command registered in that interpreter to handle background errors via the interp bgerror command — passing along the captured values as arguments. That registered handler command is meant to report the exception in whatever way makes sense for the application. The handler command receives two arguments: the result of the interp, and the return options of the interp at the time the error occurred.

If the application registers no handler command? The default handler command will attempt to call bgerror to report the error. And if an error condition pops up while invoking the handler command, then Tcl_BackgroundException just reports the error itself by printing a message on the standard error file. Not ideal, but it's giving resourceful. 💅

Lowkey important: Tcl_BackgroundException does not invoke the handler command immediately, because that could potentially interfere with scripts that are in process at the time the error occurred. Instead it invokes the handler command later, as an idle callback. Patience is the whole point, bestie.

It is possible for many background exceptions to accumulate before the handler command is invoked. When that happens, each of the exceptions is processed in order. But — and this is the plot twist — if the handler command returns a break exception, then all remaining error reports for the interpreter are skipped. Gone. Skipped. Bye. 👑

The Tcl_BackgroundError routine is an older and simpler interface, useful when the exception code you're reporting is TCL_ERROR. It is equivalent to:

Tcl_BackgroundException(interp, TCL_ERROR);

---

🌈 KEYWORDS 🌈

background, bgerror, error, interp

---

Okay that's the whole page, mwah. 💜 This one comes from the Tcl manual, version 7.5, and it's filed under the page name Tcl_BackgroundError(3) — go off, icon, and thanks for reading the whole thing, ily. 🦋