1Tcl_BackgroundError(3) Tcl Library Procedures Tcl_BackgroundError(3)
2______________________________________________________________________________
6
8 Tcl_BackgroundError - report Tcl error that occurred in background pro‐
9 cessing
10
12 #include <tcl.h>
13 Tcl_BackgroundError(interp)
15
17 Tcl_Interp *interp (in) Interpreter in which the error
18 occurred.
19_________________________________________________________________
20
23 This procedure is typically invoked when a Tcl error occurs during
24 “background processing” such as executing an event handler. When such
25 an error occurs, the error condition is reported to Tcl or to a widget
26 or some other C code, and there is not usually any obvious way for that
27 code to report the error to the user. In these cases the code calls
28 Tcl_BackgroundError with an interp argument identifying the interpreter
29 in which the error occurred. At the time Tcl_BackgroundError is
30 invoked, the interpreter's result is expected to contain an error mes‐
31 sage. Tcl_BackgroundError will invoke the command registered in that
32 interpreter to handle background errors by the interp bgerror command.
33 The registered handler command is meant to report the error in an
34 application-specific fashion. The handler command receives two argu‐
35 ments, the result of the interp, and the return options of the interp
36 at the time the error occurred. If the application registers no han‐
37 dler command, the default handler command will attempt to call bgerror
38 to report the error. If an error condition arises while invoking the
39 handler command, then Tcl_BackgroundError reports the error itself by
40 printing a message on the standard error file.
41 Tcl_BackgroundError does not invoke the handler command immediately
43 because this could potentially interfere with scripts that are in
44 process at the time the error occurred. Instead, it invokes the han‐
45 dler command later as an idle callback.
46 It is possible for many background errors to accumulate before the han‐
48 dler command is invoked. When this happens, each of the errors is pro‐
49 cessed in order. However, if the handle command returns a break excep‐
50 tion, then all remaining error reports for the interpreter are skipped.
51
54 background, bgerror, error, interp
55Tcl 7.5 Tcl_BackgroundError(3)