Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 oc-
					curred.

       int code	(in)			The exceptional	return code to be  re-
					ported.
______________________________________________________________________________

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	condi-
       tion 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 ex-
       ception.	 The state of the interpreter, including any error message  in
       the interpreter result, and the values of any entries in	the return op-
       tions  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 in-
       terp bgerror command, passing the captured values  as  arguments.   The
       registered  handler  command is meant to	report the exception in	an ap-
       plication-specific fashion.  The	handler	 command  receives  two	 argu-
       ments,  the  result of the interp, and the return options of the	interp
       at the time the error occurred.	If the application registers  no  han-
       dler  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 han-
       dler 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 use-
       ful 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_BackgroundError.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help