1Tcl_BackgroundError(3) Tcl Library Procedures Tcl_BackgroundError(3)
2______________________________________________________________________________
6
8 Tcl_BackgroundException, Tcl_BackgroundError - report Tcl exception
9 that occurred in background processing
10
12 #include <tcl.h>
13 Tcl_BackgroundException(interp, code)
15 Tcl_BackgroundError(interp)
17
19 Tcl_Interp *interp (in) Interpreter in which the exception
20 occurred.
21 int code (in) The exceptional return code to be
23 reported.
24______________________________________________________________________________
25
28 This procedure is typically invoked when a Tcl exception (any return
29 code other than TCL_OK) occurs during “background processing” such as
30 executing an event handler. When such an exception occurs, the condi‐
31 tion is reported to Tcl or to a widget or some other C code, and there
32 is not usually any obvious way for that code to report the exception to
33 the user. In these cases the code calls Tcl_BackgroundException with
34 an interp argument identifying the interpreter in which the exception
35 occurred, and a code argument holding the return code value of the
36 exception. The state of the interpreter, including any error message
37 in the interpreter result, and the values of any entries in the return
38 options dictionary, is captured and saved. Tcl_BackgroundException
39 then arranges for the event loop to invoke at some later time the com‐
40 mand registered in that interpreter to handle background errors by the
41 interp bgerror command, passing the captured values as arguments. The
42 registered handler command is meant to report the exception in an
43 application-specific fashion. The handler command receives two argu‐
44 ments, the result of the interp, and the return options of the interp
45 at the time the error occurred. If the application registers no han‐
46 dler command, the default handler command will attempt to call bgerror
47 to report the error. If an error condition arises while invoking the
48 handler command, then Tcl_BackgroundException reports the error itself
49 by printing a message on the standard error file.
50 Tcl_BackgroundException does not invoke the handler command immediately
52 because this could potentially interfere with scripts that are in
53 process at the time the error occurred. Instead, it invokes the han‐
54 dler command later as an idle callback.
55 It is possible for many background exceptions to accumulate before the
57 handler command is invoked. When this happens, each of the exceptions
58 is processed in order. However, if the handler command returns a break
59 exception, then all remaining error reports for the interpreter are
60 skipped.
61 The Tcl_BackgroundError routine is an older and simpler interface use‐
63 ful when the exception code reported is TCL_ERROR. It is equivalent
64 to:
65 Tcl_BackgroundException(interp, TCL_ERROR);
67
70 background, bgerror, error, interp
71Tcl 7.5 Tcl_BackgroundError(3)