diff options
Diffstat (limited to 'doc/BackgdErr.3')
| -rw-r--r-- | doc/BackgdErr.3 | 33 |
1 files changed, 19 insertions, 14 deletions
diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3 index 532bb44..1e46b03 100644 --- a/doc/BackgdErr.3 +++ b/doc/BackgdErr.3 @@ -24,7 +24,8 @@ Interpreter in which the error occurred. .SH DESCRIPTION .PP This procedure is typically invoked when a Tcl error occurs during -``background processing'' such as executing an event handler. +.QW "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. @@ -32,25 +33,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an \fIinterp\fR argument identifying the interpreter in which the error occurred. At the time \fBTcl_BackgroundError\fR is invoked, the interpreter's result is expected to contain an error message. -\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR -Tcl command to report the error in an application-specific fashion. -If no \fBbgerror\fR command exists, or if it returns with an error condition, -then \fBTcl_BackgroundError\fR reports the error itself by printing -a message on the standard error file. +\fBTcl_BackgroundError\fR will invoke the command registered +in that interpreter to handle background errors by the +\fBinterp bgerror\fR 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 \fBbgerror\fR to report +the error. If an error condition arises while invoking the +handler command, then \fBTcl_BackgroundError\fR reports the +error itself by printing a message on the standard error file. .PP -\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately +\fBTcl_BackgroundError\fR 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 \fBbgerror\fR later as an idle callback. -\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and -\fBerrorCode\fR variables and restores these values just before -invoking \fBbgerror\fR. +Instead, it invokes the handler command later as an idle callback. .PP It is possible for many background errors to accumulate before -\fBbgerror\fR is invoked. When this happens, each of the errors -is processed in order. However, if \fBbgerror\fR returns a +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. .SH KEYWORDS -background, bgerror, error +background, bgerror, error, interp |