TIP #322 IMPLEMENTATION

* doc/NRE.3 (new file): Added documentation of the published
API for Non-Recursive Evaluation (NRE).

1 files changed, 303 insertions, 0 deletions

diff --git a/doc/NRE.3 b/doc/NRE.3
new file mode 100644
index 0000000..edddd7b
--- /dev/null
+++ b/doc/NRE.3
@@ -0,0 +1,303 @@
+.\"

+.\" Copyright (c) 2008 by Kevin B. Eknny.

+.\"

+

+'\" See the file "license.terms" for information on usage and redistribution

+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

+'\" 

+'\" RCS: @(#) $Id: NRE.3,v 1.1 2008/12/12 04:38:12 kennykb Exp $

+'\" 

+.so man.macros

+.TH NRE 3 8.6 Tcl "Tcl Library Procedures"

+.BS

+.SH NAME

+Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.

+.SH SYNOPSIS

+.nf

+\fB#include <tcl.h>\fR

+.sp

+Tcl_Command

+\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData, deleteProc\fR)

+.sp

+int

+\fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)

+.sp

+int

+\fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)

+.sp

+int

+\fBTcl_NREvalObjv\fR(\fIinterp, objc, objv, flags\fR)

+.sp

+int

+\fBTcl_NRCmdSwap\fR(\fIinterp, cmd, objc, objv, flags\fR)

+.sp

+void

+\fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR)

+.fi

+.SH ARGUMENTS

+.AS Tcl_CmdDeleteProc *postProcPtr in

+.AP Tcl_Interp *interp in

+Interpreter in which to create or evaluate a command.

+.AP char *cmdName in

+Name of a new command to create.

+.AP Tcl_ObjCmdProc *proc in

+Implementation of a command that will be called whenever \fIcmdName\fR

+is invoked as a command in the unoptimized way.

+.AP Tcl_ObjCmdProc *nreProc in

+Implementation of a command that will be called whenever \fIcmdName\fR 

+is invoked and requested to conserve the C stack.

+.AP ClientData clientData in

+Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,

+\fIdeleteProc\fR and \fIobjProc\fR.

+.AP Tcl_CmdDeleteProc *deleteProc in/out

+Procedure to call before \fIcmdName\fR is deleted from the interpreter.

+This procedure allows for command-specific cleanup. If \fIdeletProc\fR

+is \fBNULL\fR, then no procedure is called before the command is deleted.

+.AP int objc in

+Count of parameters provided to the implementation of a command.

+.AP Tcl_Obj **objv in

+Pointer to an array of Tcl objects. Each object holds the value of a

+single word in the command to execute.

+.AP Tcl_Obj *objPtr in

+Pointer to a Tcl_Obj whose value is a script to execute.

+.AP int flags in

+ORed combination of flag bits that specify additional options.

+\fBTCL_EVAL_GLOBAL\fR is the only flag that is currently supported.

+.\" TODO: This is a lie. But kbk didn't grasp TCL_EVAL_INVOKE and

+.\"       TCL_EVAL_NOERR well enough to document them.

+.AP Tcl_Command cmd in

+.AP Tcl_NRPostProc *postProcPtr in

+Pointer to a function that will be invoked when the command currently

+executing in the interpreter designated by \fIinterp\fR completes.

+.AP ClientData data0 in

+.AP ClientData data1 in

+.AP ClientData data2 in

+.AP ClientData data3 in

+\fIdata0\fR through \fIdata3\fR are four one-word values that will be passed

+to the function designated by \fIpostProcPtr\fR when it is invoked.

+.BE

+.SH DESCRIPTION

+.PP 

+This series of C functions provides an interface whereby commands that

+are implemented in C can be evaluated, and invoke Tcl commands scripts

+and scripts, without consuming space on the C stack. The non-recursive

+evaluation is done by installing a \fItrampoline\fR, a small piece of

+code that invokes a command or script, and then executes a series of

+callbacks when the command or script returns. 

+.PP

+The \fBTcl_NRCreateCommand\fR function creates a Tcl command in the

+interpreter designated by \fIinterp\fR that is prepared to handle

+nonrecursive evaluation with a trampoline. The \fIcmdName\fR argument

+gives the name of the new command. If \fIcmdName\fR contains any

+namespace qualifiers, then the new command is added to the specified

+namespace; otherwise, it is added to the global namespace. \fIproc\fR

+gives the procedure that will be called when the interpreter wishes to

+evaluate the command in an unoptimized manner, and \fInreProc\fR is

+the procedure that will be called when the interpreter wishes to

+evaluate the command using a trampoline. \fIdeleteProc\fR is a

+function that will be called before the command is deleted from the

+interpreter. When any of the three functions is invoked, it is passed

+the \fIclientData\fR parameter.

+.PP

+\fBTcl_NRCreateCommand\fR deletes any existing command

+\fIname\fR already associated with the interpreter

+(however see below for an exception where the existing command

+is not deleted).

+It returns a token that may be used to refer

+to the command in subsequent calls to \fBTcl_GetCommandName\fR.

+If \fBTcl_NRCreateCommand\fR is called for an interpreter that is in

+the process of being deleted, then it does not create a new command,

+does not delete any existing command of the same name, and returns NULL.

+.PP

+The \fIproc\fR and \fInreProc\fR function are expected to conform to

+all the rules set forth for the \fIproc\fR argument to

+\fBTcl_CreateObjCommand\fR(3) (\Iq.v.\fR).

+.PP

+When a command that is written to cope with evaluation via trampoline

+is invoked without a trampoline on the stack, it will usually respond

+to the invocation by creating a trampoline and calling the

+trampoline-enabled implementation of the same command. This call is done by

+means of \fBTcl_NRCallObjProc\fR. In the call to

+\fBTcl_NRCallObjProc\fR, the \fIinterp\fR, \fIclientData\fR,

+\fIobjc\fR and \fIobjv\fR parameters should be the same ones that were

+passed to \fIproc\fR. The \fInreProc\fR parameter should designate the

+trampoline-enabled implementation of the command.

+.PP

+\fBTcl_NREvalObj\fR arranges for the script contained in \fIobjPtr\fR

+to be evaluated in the interpreter designated by \fIinterp\fR after

+the current command (which must be trampoline-enabled) returns. It is

+the method by which a command may invoke a script without consuming

+space on the C stack. Similarly, \fBTcl_NREvalObjv\fR arranges to

+invoke a single Tcl command whose words have already been separated

+and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the

+words of the command to be evaluated when execution reaches the

+trampoline.

+.PP

+\fBTcl_NRCmdSwap allows for trampoline evaluation of a command whose

+resolution is already known.  The \fIcmd\fR parameter gives a

+\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCmd\fR or

+\fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in

+the trampoline; this command must match the word in \fIobjv[0]\fR.

+The remaining arguments are as for \fBTcl_NREvalObj\fR.

+.PP

+\fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR

+all accept a \fIflags\fR parameter, which is an OR-ed-together set of

+bits to control evaluation. At the present time, the only flag

+available to callers is \fBTCL_EVAL_GLOBAL\fR. 

+.\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE

+.\"       and TCL_EVAL_NOERR?

+If the \fBTCL_EVAL_GLOBAL\fR flag is set, the script or command is

+evaluated in the global namespace. If it is not set, it is evaluated

+in the current namespace.

+.PP

+All three of the routines return \fBTCL_OK\fR if command invocation

+has been scheduled successfully. If for any reason command invocation

+cannot be scheduled (for example, if the interpreter is unable to find

+the requested command), they return \fBTCL_ERROR\fR with an

+appropriate message left in the interpreter's result.

+.PP

+\fBTcl_NRAddCallback\fR arranges to have a C function called when the

+current trampoline-enabled command in the Tcl interpreter designated

+by \fIinterp\fR returns.  The \fIpostProcPtr\fR argument is a pointer

+to the callback function, which must have arguments and return value

+consistent with the \fBTcl_NRPostProc\fR data type:

+.PP

+.CS

+typedef int

+\fBTcl_NRPostProc\fR(

+    \fBClientData\fR \fIdata\fR[],

+    \fBTcl_Interp\fR *\fIinterp\fR,

+    int \fIresult\fR);

+.CE

+.PP

+When the trampoline invokes the callback function, the \fIdata\fR

+parameter will point to an array containing the four one-word

+quantities that were passed to \fBTcl_NRAddCallback\fR in the

+\fIdata0\fR through \fIdata3\fR parameters. The Tcl interpreter will

+be designated by the \fIinterp\fR parameter, and the \fIresult\fR

+parameter will contain the result (\fBTCL_OK\fR, \fBTCL_ERROR\fR,

+\fBTCL_RETURN\fR, \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR) that was

+returned by the command evaluation. The callback function is expected,

+in turn, either to return a \fIresult\fR to control further evaluation.

+.PP

+Multiple \fBTcl_NRAddCallback\fR invocations may request multiple

+callbacks, which may be to the same or different callback

+functions. If multiple callbacks are requested, they are executed in

+last-in, first-out order, that is, the most recently requested

+callback is executed first.

+.SH EXAMPLE

+.PP

+The usual pattern for Tcl commands that invoke other Tcl commands

+is something like:

+.PP

+.CS

+int \fITheCmdObjProc\fR(

+    \fBClientData\fR \fIclientData\fR,

+    \fBTcl_Interp\fR *\fIinterp\fR,

+    int \fIobjc\fR,

+    \fBTcl_Obj\fR *const \fIobjv\fR[])

+{

+    int \fIresult\fR;

+    \fBTcl_Obj\fR *\fIobjPtr\fR;

+    \fI... preparation ...\fR

+    \fIresult\fR = \fBTcl_EvalObjEx\fR(\fIinterp\fR, \fIobjPtr\fR, 0);

+    \fI... postprocessing ...\fR

+    return \fIresult\fR;

+}

+\fBTcl_CreateObjCommand\fR(\fIinterp\fR, "theCommand",

+	                   \fITheCmdObjProc\fR, \fIclientData\fR,

+                           \fITheCmdDeleteProc\fR);

+.CE

+.PP

+To enable a command like this one for trampoline-based evaluation,

+it must be split into three pieces:

+.IP \(bu

+A non-trampoline implementation, \fITheCmdNewObjProc\fR,

+which will simply create a trampoline

+and invoke the trampoline-based implementation.

+.IP \(bu

+A trampoline-enabled implementation, \fITheCmdNRObjProc\fR.  This

+function will perform the initialization, request that the trampoline

+call the postprocessing routine after command evaluation, and finally,

+request that the trampoline call the inner command.

+.IP \(bu

+A postprocessing routine, \fITheCmdPostProc\fR. This function will

+perform the postprocessing formerly done after the return from the

+inner command in \fITheCmdObjProc\fR.

+.PP

+The non-trampoline implementation is simple and stylized, containing

+a single statement:

+.PP

+.CS

+int

+TheCmdNewObjProc

+    \fBClientData\fR \fIclientData\fR,

+    \fBTcl_Interp\fR *\fIinterp\fR,

+    int \fIobjc\fR,

+    \fBTcl_Obj\fR *const \fIobjv\fR[])

+{

+    return \fBTcl_NRCallObjProc\fR(\fIinterp, name,\fR

+        \fITheCmdNRObjProc, clientData, objc, objv\fR);

+}

+.CE

+.PP

+The trampoline-enabled implementation requests postprocessing,

+and returns to the trampoline requesting command evaluation.

+.PP

+.CS

+int

+TheCmdNRObjProc

+    \fBClientData\fR \fIclientData\fR,

+    \fBTcl_Interp\fR *\fIinterp\fR,

+    int \fIobjc\fR,

+    \fBTcl_Obj\fR *const \fIobjv\fR[])

+{

+    \fI... preparation ...\fR

+    \fBTcl_NRAddCallback\fR(\fIinterp, TheCmdPostProc,\fR

+        \fIdata0, data1, data2, data3\fR);

+            /* \fIdata0 .. data3\fR are up to four one-word items

+             * to pass to the postprocessing procedure */

+    return \fBTcl_NREvalObj\fR(\fIinterp, objPtr, 0\fR);

+}

+.CE

+.PP

+The postprocessing procedure does whatever the original command did

+upon return from the inner evaluation.

+.PP

+.CS

+int

+TheCmdNRPostProc

+    \fBClientData\fR \fIdata\fR[],

+    \fBTcl_Interp\fR *\fIinterp\fR,

+    int \fRresult\fR

+{

+    /* \fIdata[0] .. data[4]\fR are the four words of data

+     * passed to \fBTcl_NREvalObj\fR */

+    \fI... postprocessing ...\fR

+    return result;

+}

+.CE

+.PP

+If \fItheCommand\fR is a command that results in multiple commands or

+scripts being evaluated, its postprocessing routine may schedule

+additional postprocessing and then request another command evaluation

+by means of \fBTcl_NREvalObj\fR or one of the other evaluation

+routines. Looping and sequencing constructs may be implemented in this way.

+.PP

+Finally, to install a trampoline-enabled command in the interpreter,

+\fBTcl_NRCreateCommand\fR is used in place of

+\fBTcl_CreateObjCommand\fR.  It accepts two command procedures instead

+of one. The first is for use when no trampoline is yet on the stack,

+and the second is for use when there is already a trampoline in place.

+.PP

+.CS

+\fBTcl_NRCreateCommand\fR(\fIinterp\fR, "theCommand",

+    \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, \fIclientData\fR,

+    \fITheCmdDeleteProc\fR);

+.CE

+.SH "SEE ALSO"

+Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3)

+.SH KEYWORDS

+stackless, nonrecursive, execute, command, global, object, result, script

+.SH COPYRIGHT

+Copyright (c) 2008 by Kevin B. Kenny
\ No newline at end of file