trusty (3) Tcl_BackgroundError.3tcl.gz

NAME

       Tcl_BackgroundError - report Tcl error that occurred in background processing

SYNOPSIS

       #include <tcl.h>

       Tcl_BackgroundError(interp)

ARGUMENTS

       Tcl_Interp   *interp   (in)      Interpreter in which the error occurred.
_________________________________________________________________

DESCRIPTION

       This  procedure  is  typically  invoked  when a Tcl error occurs during ``background processing'' such as
       executing an event handler.  When such an error occurs, the error 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 error
       to the user.  In these cases the code calls Tcl_BackgroundError with an interp argument  identifying  the
       interpreter  in  which the error occurred.  At the time Tcl_BackgroundError is invoked, the interpreter's
       result is expected to contain an error message.  Tcl_BackgroundError will invoke the bgerror Tcl  command
       to  report  the error in an application-specific fashion.  If no bgerror command exists, or if it returns
       with an error condition, then Tcl_BackgroundError reports the error itself by printing a message  on  the
       standard error file.

       Tcl_BackgroundError  does  not  invoke  bgerror immediately because this could potentially interfere with
       scripts that are in process at the time the error occurred.  Instead, it invokes bgerror later as an idle
       callback.   Tcl_BackgroundError  saves  the  values of the errorInfo and errorCode variables and restores
       these values just before invoking bgerror.

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

KEYWORDS

       background, bgerror, error