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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_BackgroundError.tcl87&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help