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  command  registered
       in  that  interpreter  to handle background errors by the interp bgerror command.  The registered handler
       command is meant to report the error 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_BackgroundError reports the error itself by printing a message on the standard error file.

       Tcl_BackgroundError 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 errors to accumulate before the handler command is invoked.  When this
       happens,  each  of  the  errors  is  processed  in order.  However, if the handle command returns a break
       exception, then all remaining error reports for the interpreter are skipped.

KEYWORDS

       background, bgerror, error, interp