Refine documentation for Tcl_NR* functions.

1 files changed, 84 insertions, 176 deletions

diff --git a/doc/NRE.3 b/doc/NRE.3
index ff0d108..6078a53 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 2008 by Kevin B. Kenny.
+.\" Copyright (c) 2018 by Nathan Coulter. 
 .\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -38,43 +39,39 @@ void
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *interp in
 .AP Tcl_Interp *interp in
-Interpreter in which to create or evaluate a command.
+The relevant Interpreter.
 .AP char *cmdName in
-Name of a new command to create.
+Name of the 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.
+Called in order to evaluate a command.  Is often just a small wrapper that uses
+\fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline.  Behaves
+in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
+(\fIq.v.\fR).
 .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.
+Called instead of \fIproc\fR when a trampoline is already in use.
 .AP ClientData clientData in
-Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,
-\fIdeleteProc\fR and \fIobjProc\fR.
+Arbitrary one-word value 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 \fIdeleteProc\fR
-is \fBNULL\fR, then no procedure is called before the command is deleted.
+Called before \fIcmdName\fR is deleted from the interpreter, allowing for
+command-specific cleanup. May be NULL.
 .AP int objc in
-Count of parameters provided to the implementation of a command.
+Number of items in \fIobjv\fR.
 .AP Tcl_Obj **objv in
-Pointer to an array of Tcl values. Each value holds the value of a
-single word in the command to execute.
+Words in the command.
 .AP Tcl_Obj *objPtr in
-Pointer to a Tcl_Obj whose value is a script or expression to execute.
+A script or expression to evaluate.
 .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.
+As described for \fITcl_EvalObjv\fR.
+.PP
 .AP Tcl_Command cmd in
-Token for a command that is to be used instead of the currently
-executing command.
+Token to use instead of one derived from the first word of \fIobjv\fR in order
+to evaluate a command.
 .AP Tcl_Obj *resultPtr out
-Pointer to an unshared Tcl_Obj where the result of expression
-evaluation is written.
+Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
+the return code is TCL_OK.
 .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.
+A function to push.
 .AP ClientData data0 in
 .AP ClientData data1 in
 .AP ClientData data2 in
@@ -84,98 +81,51 @@ 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) (\fIq.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\fR allows for trampoline evaluation of a command whose
-resolution is already known.  The \fIcmd\fR parameter gives a
-\fBTcl_Command\fR token (returned from \fBTcl_CreateObjCommand\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_NREvalObjv\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 supported 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
-\fBTcl_NRExprObj\fR arranges for the expression 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 evaluate a Tcl expression without consuming
-space on the C stack.  The argument \fIresultPtr\fR is a pointer to an
-unshared Tcl_Obj where the result of expression evaluation is to be written.
-If expression evaluation returns any code other than TCL_OK, the
-\fIresultPtr\fR value is left untouched.
-.PP
-All of the routines return \fBTCL_OK\fR if command or expression invocation
-has been scheduled successfully. If for any reason the scheduling cannot
-be completed (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:
+These functions provide an interface to the function stack that an interpreter
+iterates through to evaluate commands.  The routine behind a command is
+implemented by an initial function and any additional functions that the
+routine pushes onto the stack as it progresses.  The interpreter itself pushes
+functions onto the stack to react to the end of a routine and to exercise other
+forms of control such as switching between in-progress stacks and the
+evaluation of other scripts at additional levels without adding frames to the C
+stack.  To execute a routine, the initial function for the routine is called
+and then a small bit of code called a \fItrampoline\fR iteratively takes
+functions off the stack and calls them, using the value of the last call as the
+value of the routine.
+.PP
+\fBTcl_NRCallObjProc\fR calls \fInreProc\fR using a new trampoline.
+.PP
+\fBTcl_NRCreateCommand\fR, an alternative to \fBTcl_CreateObjCommand\fR,
+resolves \fIcmdName\fR, which may contain namespace qualifiers, relative to the
+current namespace, creates a command by that name, and returns a token for the
+command which may be used in subsequent calls to \fBTcl_GetCommandName\fR.
+Except for a few cases noted below any existing command by the same name is
+first deleted.  If \fIinterp\fR is in the process of being deleted
+\fBTcl_NRCreateCommand\fR does not create any command, does not delete any
+command, and returns NULL.
+.PP
+\fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but
+consumes no space on the C stack.
+.PP
+\fBTcl_NREvalObjv\fR pushes a function that is like \fBTcl_EvalObjv\fR but
+consumes no space on the C stack.
+.PP
+\fBTcl_NRCmdSwap\fR is like \fBTcl_NREvalObjv\fR, but uses \fIcmd\fR, a token
+previously returned by \fBTcl_CreateObjCommand\fR or
+\fBTcl_GetCommandFromObj\fR, instead of resolving the first word of \fIobjv\fR.
+.  The name of this command must be the same as \fIobjv[0]\fR.
+.PP
+\fBTcl_NRExprObj\fR pushes a function that evaluates \fIobjPtr\fR as an
+expression in the same manner as \fBTcl_ExprObj\fR but without consuming space
+on the C stack.
+.PP
+All of the functions return \fBTCL_OK\fR if the evaluation of the script,
+command, or expression has been scheduled successfully.  Otherwise (for example
+if the command name cannot be resolved), they return \fBTCL_ERROR\fR and store
+a message as the interpreter's result.
+.PP
+\fBTcl_NRAddCallback\fR pushes \fIpostProcPtr\fR.  The signature for
+\fBTcl_NRPostProc\fR is:
 .PP
 .CS
 typedef int
@@ -185,25 +135,13 @@ typedef int
         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.
+\fIdata\fR is a pointer to an array containing \fIdata0\fR through \fIdata3\fR.
+\fIresult\fR is the value returned by the previous function implementing part
+the routine.
 .SH EXAMPLE
 .PP
-The usual pattern for Tcl commands that invoke other Tcl commands
-is something like:
+The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C
+stack, to evalute a script:
 .PP
 .CS
 int
@@ -228,28 +166,17 @@ int
         \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
 .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:
+To avoid consuming space on the C stack, \fITheCmdOldObjProc\fR is renamed to
+\fITheCmdNRObjProc\fR and the postprocessing step is split into a separate
+function, \fITheCmdPostProc\fR, which is pushed onto the function stack.
+\fITcl_EvalObjEx\fR is replaced with \fITcl_NREvalObj\fR, which uses a
+trampoline instead of consuming space on the C stack.  A new version of
+\fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to
+call \fITheCmdNRObjProc\fR:
 .PP
 .CS
 int
-\fITheCmdNewObjProc\fR(
+\fITheCmdOldObjProc\fR(
     ClientData clientData,
     Tcl_Interp *interp,
     int objc,
@@ -260,9 +187,6 @@ int
 }
 .CE
 .PP
-The trampoline-enabled implementation requests postprocessing,
-and returns to the trampoline requesting command evaluation.
-.PP
 .CS
 int
 \fITheCmdNRObjProc\fR
@@ -284,9 +208,6 @@ int
 }
 .CE
 .PP
-The postprocessing procedure does whatever the original command did
-upon return from the inner evaluation.
-.PP
 .CS
 int
 \fITheCmdNRPostProc\fR(
@@ -303,26 +224,13 @@ int
 }
 .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.
+Any function comprising a routine can push other functions, making it possible
+implement looping and sequencing constructs using the function stack.
 .PP
-.CS
-\fBTcl_NRCreateCommand\fR(interp, "theCommand",
-        \fITheCmdNewObjProc\fR, \fITheCmdNRObjProc\fR, clientData,
-        TheCmdDeleteProc);
-.CE
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
 .SH KEYWORDS
 stackless, nonrecursive, execute, command, global, value, result, script
 .SH COPYRIGHT
-Copyright (c) 2008 by Kevin B. Kenny
+Copyright (c) 2008 by Kevin B. Kenny.
+Copyright (c) 2018 by Nathan Coulter.