Tcl_Cancel(3tcl) Tcl Library Procedures Tcl_Cancel(3tcl)
______________________________________________________________________________
NAME
Tcl_CancelEval, Tcl_Canceled - cancel Tcl scripts
SYNOPSIS
#include <tcl.h>
int
Tcl_CancelEval(interp, resultObjPtr, clientData, flags)
int
Tcl_Canceled(interp, flags)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to cancel the
script.
Tcl_Obj *resultObjPtr (in) Error message to use in the cancella-
tion, or NULL to use a default mes-
sage. If not NULL, this object will
have its reference count decremented
before Tcl_CancelEval returns.
int flags (in) ORed combination of flag bits that
specify additional options. For
Tcl_CancelEval, only TCL_CANCEL_UNWIND
is currently supported. For Tcl_Can-
celed, only TCL_LEAVE_ERR_MSG and
TCL_CANCEL_UNWIND are currently sup-
ported.
ClientData clientData (in) Currently reserved for future use. It
should be set to NULL.
______________________________________________________________________________
DESCRIPTION
Tcl_CancelEval cancels or unwinds the script in progress soon after the
next invocation of asynchronous handlers, causing TCL_ERROR to be the
return code for that script. This function is thread-safe and may be
called from any thread in the process.
Tcl_Canceled checks if the script in progress has been canceled and re-
turns TCL_ERROR if it has. Otherwise, TCL_OK is returned. Extensions
can use this function to check to see if they should abort a long run-
ning command. This function is thread sensitive and may only be called
from the thread the interpreter was created in.
FLAG BITS
Any ORed combination of the following values may be used for the flags
argument to procedures such as Tcl_CancelEval:
TCL_CANCEL_UNWIND This flag is used by Tcl_CancelEval and Tcl_Can-
celed. For Tcl_CancelEval, if this flag is set,
the script in progress is canceled and the evalua-
tion stack for the interpreter is unwound. For
Tcl_Canceled, if this flag is set, the script in
progress is considered to be canceled only if the
evaluation stack for the interpreter is being un-
wound.
TCL_LEAVE_ERR_MSG This flag is only used by Tcl_Canceled; it is ig-
nored by other procedures. If an error is returned
and this bit is set in flags, then an error message
will be left in the interpreter's result, where it
can be retrieved with Tcl_GetObjResult or Tcl_Get-
StringResult. If this flag bit is not set then no
error message is left and the interpreter's result
will not be modified.
SEE ALSO
interp(3tcl), Tcl_Eval(3tcl), TIP 285
KEYWORDS
cancel, unwind
Tcl 8.6 Tcl_Cancel(3tcl)
Generated by dwww version 1.14 on Thu Jan 23 01:24:50 CET 2025.