DragonFly On-Line Manual Pages

Tcl_BackgroundError(3)      Tcl Library Procedures      Tcl_BackgroundError(3)

______________________________________________________________________________

NAME
       Tcl_BackgroundException, Tcl_BackgroundError - report Tcl exception
       that occurred in background processing

SYNOPSIS
       #include <tcl.h>

       Tcl_BackgroundException(interp, code)

       Tcl_BackgroundError(interp)

ARGUMENTS
       Tcl_Interp *interp (in)          Interpreter in which the exception
                                        occurred.

       int code (in)                    The exceptional return code to be
                                        reported.
______________________________________________________________________________

DESCRIPTION
       This procedure is typically invoked when a Tcl exception (any return
       code other than TCL_OK) occurs during "background processing" such as
       executing an event handler.  When such an exception occurs, the
       condition is reported to Tcl or to a widget or some other C code, and
       there is not usually any obvious way for that code to report the
       exception to the user.  In these cases the code calls
       Tcl_BackgroundException with an interp argument identifying the
       interpreter in which the exception occurred, and a code argument
       holding the return code value of the exception.  The state of the
       interpreter, including any error message in the interpreter result, and
       the values of any entries in the return options dictionary, is captured
       and saved.  Tcl_BackgroundException then arranges for the event loop to
       invoke at some later time the command registered in that interpreter to
       handle background errors by the interp bgerror command, passing the
       captured values as arguments.  The registered handler command is meant
       to report the exception in an application-specific fashion.  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.

       Tcl_BackgroundException does not invoke the handler command immediately
       because this 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.

       It is possible for many background exceptions to accumulate before the
       handler command is invoked.  When this happens, each of the exceptions
       is processed in order.  However, if the handler command returns a break
       exception, then all remaining error reports for the interpreter are
       skipped.

       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);

KEYWORDS
       background, bgerror, error, interp

Tcl                                   7.5               Tcl_BackgroundError(3)