TIP 285 Implementation

3 files changed, 69 insertions, 12 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
diff --git a/doc/after.n b/doc/after.n
index e79cbb9..4e5dfdd 100644
--- a/doc/after.n
+++ b/doc/after.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: after.n,v 1.10 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: after.n,v 1.11 2008/06/13 05:45:07 mistachkin Exp $
 '\" 
 .so man.macros
 .TH after n 7.5 Tcl "Tcl Built-In Commands"
@@ -67,7 +67,7 @@ This command also cancels the execution of a delayed command.
 The \fIscript\fR arguments are concatenated together with space
 separators (just as in the \fBconcat\fR command).
 If there is a pending command that matches the string, it is
-cancelled and will never be executed;  if no such command is
+canceled and will never be executed;  if no such command is
 currently pending then the \fBafter cancel\fR command has no effect.
 .TP
 \fBafter idle \fIscript \fR?\fIscript script ...\fR?
@@ -90,7 +90,7 @@ event handlers created by the \fBafter\fR command for this
 interpreter.
 If \fIid\fR is supplied, it specifies an existing handler;
 \fIid\fR must have been the return value from some previous call
-to \fBafter\fR and it must not have triggered yet or been cancelled.
+to \fBafter\fR and it must not have triggered yet or been canceled.
 In this case the command returns a list with two elements.
 The first element of the list is the script associated
 with \fIid\fR, and the second element is either
diff --git a/doc/interp.n b/doc/interp.n
index 5612226..f89594c 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -1,14 +1,15 @@
 '\"
 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 2004 Donal K. Fellows
+'\" 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: interp.n,v 1.38 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.39 2008/06/13 05:45:07 mistachkin Exp $
 '\" 
 .so man.macros
-.TH interp n 7.6 Tcl "Tcl Built-In Commands"
+.TH interp n 8.6 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -144,6 +145,22 @@ what to set the interpreter's background error to. See the
 \fBBACKGROUND ERROR HANDLING\fR section for more details.
 .VE 8.5
 .TP
+\fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR?
+.VS 8.6
+Cancels the script being evaluated in the interpreter identified by
+\fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for
+the interpreter is unwound until an enclosing catch command is found or
+there are no further invocations of the interpreter left on the call
+stack. With the \fB\-unwind\fR switch the evaluation stack for the
+interpreter is unwound without regard to any intervening catch command
+until there are no further invocations of the interpreter left on the
+call stack. The \fB\-\|\-\fR switch can be used to mark the end of
+switches; it may be needed if \fIpath\fR is an unusual value such
+as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the
+error message string; otherwise, a default error message string will be
+used.
+.VE 8.6
+.TP
 \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
 Creates a slave interpreter identified by \fIpath\fR and a new command,
 called a \fIslave command\fR. The name of the slave command is the last
@@ -811,6 +828,6 @@ set i [\fBinterp create\fR]
 .CE
 .VE 8.5
 .SH "SEE ALSO"
-bgerror(n), load(n), safe(n), Tcl_CreateSlave(3)
+bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3)
 .SH KEYWORDS
 alias, master interpreter, safe interpreter, slave interpreter