TIP 285 Implementation

1 files changed, 46 insertions, 6 deletions

diff --git a/doc/Eval.3 b/doc/Eval.3
index 79392fc..313406c 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -2,17 +2,18 @@
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
 '\" Copyright (c) 2000 Scriptics Corporation.
+'\" Copyright (c) 2006-2008 Joe Mistachkin.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Eval.3,v 1.27 2007/12/13 15:22:31 dgp Exp $
+'\" RCS: @(#) $Id: Eval.3,v 1.28 2008/06/13 05:45:07 mistachkin Exp $
 '\" 
 .so man.macros
-.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_Eval 3 8.6 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA, Tcl_CancelEval, Tcl_Canceled \- execute and cancel Tcl scripts
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -43,16 +44,25 @@ int
 .sp
 int
 \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
+.sp
+int
+\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
+.sp
+int
+\fBTcl_Canceled\fR(\fIinterp, flags\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
-Interpreter in which to execute the script.  The interpreter's result is
-modified to hold the result or error message from the script.
+Interpreter in which to execute or cancel the script.  The interpreter's
+result is modified to hold the result or error message from the script.
 .AP Tcl_Obj *objPtr in
 A Tcl object containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
+For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
+supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
+\fBTCL_CANCEL_UNWIND\fR are currently supported.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
@@ -72,6 +82,9 @@ String forming part of a Tcl script.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP ClientData clientData in
+Currently, reserved for future use.
+It should be set to NULL.
 .BE
 
 .SH DESCRIPTION
@@ -159,6 +172,17 @@ of arguments.  \fBTcl_VarEval\fR is now deprecated.
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
 list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+.PP
+\fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after
+the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be
+the return code for that script.  This function is thread-safe and may be
+called from any thread in the process.
+.PP
+\fBTcl_Canceled\fR checks if the script in progress has been canceled and
+returns \fBTCL_ERROR\fR if it has.  Otherwise, \fBTCL_OK\fR 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.
 
 .SH "FLAG BITS"
 Any ORed combination of the following values may be used for the
@@ -179,6 +203,22 @@ If this flag is set, the script is processed at global level.  This
 means that it is evaluated in the global namespace and its variable
 context consists of global variables only (it ignores any Tcl
 procedures at are active).
+.TP 23
+\fBTCL_CANCEL_UNWIND\fR
+This flag is only used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR;
+it is ignored by other procedures.  For \fBTcl_CancelEval\fR, if this
+flag is set, the script in progress is canceled and the evaluation
+stack for the interpreter is unwound.  For \fBTcl_Canceled\fR, 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.
+.TP 23
+\fBTCL_LEAVE_ERR_MSG\fR
+This flag is only used by \fBTcl_Canceled\fR; it is ignored by
+other procedures.  If an error is returned and this bit is set in
+\fIflags\fR, then an error message will be left in the interpreter's
+result, where it can be retrieved with \fBTcl_GetObjResult\fR or
+\fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
+message is left and the interpreter's result will not be modified.
 
 .SH "MISCELLANEOUS DETAILS"
 .PP
@@ -207,4 +247,4 @@ This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 
 .SH KEYWORDS
-execute, file, global, object, result, script
+cancel, execute, file, global, object, result, script, unwind