Tcl_BackgroundError(3tcl)

💖 Tcl_BackgroundException, Tcl_BackgroundError — reporting the Tcl exception that popped off during background processing 💖

okay bestie, this one lives in the Tcl library procedures (man page Tcl_BackgroundError(3tcl), hey girl hey) and it's literally all about what to do when your background code goes "oop 💀" and nobody's around to hear it.

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_BackgroundException(interp, code)

Tcl_BackgroundError(interp)

---

🌸 ARGUMENTS 🌸

• Tcl_Interp *interp (in) — the interpreter where the exception happened, like the crime scene 🕵️‍♀️
• int code (in) — the exceptional return code you're reporting, aka the receipts 💅

---

👑 DESCRIPTION 👑

so here's the vibe. You call this procedure when a Tcl exception — and by that we mean any return code that isn't TCL_OK — happens during "background processing", like when an event handler is doing its thing. When that exception hits, the condition gets reported to Tcl or to a widget or to some other C code, and usually that code has no obvious way to tell the user about it. Awkward. 🙈

That's where you come in: the code calls Tcl_BackgroundException with an interp argument that identifies the interpreter where the exception occurred, and a code argument holding the return code value of the exception. Then — and this is the iconic part — the state of the interpreter gets captured and saved, including any error message sitting in the interpreter result, plus the values of any entries in the return options dictionary. ✨

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 — and it passes the captured values as arguments. That registered handler command is meant to report the exception in whatever way makes sense for your application, main character style. 👑

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.
• If an error condition arises while invoking the handler command, then Tcl_BackgroundException reports the error itself by printing a message on the standard error file. (not the glow-up we wanted, but ok 😭)

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 a virtue, 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, one by one, no cutting the line. 🎀 But heads up: if the handler command returns a break exception, then all remaining error reports for the interpreter are skipped. bye felicia 👋

---

🦋 the older, simpler one

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

Tcl_BackgroundException(interp, TCL_ERROR);

that's it, that's the whole function, she's short and she serves 💅

---

⭐ KEYWORDS ⭐

background, bgerror, error, interp

---

and that's the whole page, periodt. this one's from the Tcl library docs, tagged Tcl 7.5 and dated 7.5 — go off, background error handling, you ate 🫶💖