1Tcl_BackgroundError(3)      Tcl Library Procedures      Tcl_BackgroundError(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_BackgroundException,  Tcl_BackgroundError  -  report  Tcl exception
9       that occurred in background processing
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_BackgroundException(interp, code)
15
16       Tcl_BackgroundError(interp)
17

ARGUMENTS

19       Tcl_Interp *interp (in)          Interpreter  in  which  the  exception
20                                        occurred.
21
22       int code (in)                    The  exceptional  return  code  to  be
23                                        reported.
24______________________________________________________________________________
25
26

DESCRIPTION

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
51       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
56       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
62       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
66              Tcl_BackgroundException(interp, TCL_ERROR);
67
68

KEYWORDS

70       background, bgerror, error, interp
71
72
73
74Tcl                                   7.5               Tcl_BackgroundError(3)
Impressum