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  cancellation, or NULL to use a default
                                        message. If  not  NULL,  this  object  will  have  its  reference  count
                                        decremented before Tcl_CancelEval returns.

       int flags (in)                   OR'ed  combination  of  flag  bits that specify additional options.  For
                                        Tcl_CancelEval, only  TCL_CANCEL_UNWIND  is  currently  supported.   For
                                        Tcl_Canceled, only TCL_LEAVE_ERR_MSG and TCL_CANCEL_UNWIND are currently
                                        supported.

       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 returns 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  running  command.   This  function  is  thread sensitive and may only be called from the thread the
       interpreter was created in.

   FLAG BITS
       Any OR'ed 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_Canceled.  For Tcl_CancelEval, if this
                           flag is set, the script in progress is canceled and  the  evaluation  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 unwound.

       TCL_LEAVE_ERR_MSG   This  flag  is  only  used by Tcl_Canceled; it is ignored 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_GetStringResult.   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)