diff options
Diffstat (limited to 'doc/NRE.3')
| -rw-r--r-- | doc/NRE.3 | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/doc/NRE.3 b/doc/NRE.3 deleted file mode 100644 index f76938a..0000000 --- a/doc/NRE.3 +++ /dev/null @@ -1,272 +0,0 @@ -.\" -.\" Copyright (c) 2008 Kevin B. Kenny. -.\" Copyright (c) 2018 Nathan Coulter. -.\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH NRE 3 8.6 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_NRCreateCommand, Tcl_NRCreateCommand2, Tcl_NRCallObjProc, Tcl_NRCallObjProc2, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, 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 -Tcl_Command -\fBTcl_NRCreateCommand2\fR(\fIinterp, cmdName, proc2, nreProc2, clientData, - deleteProc\fR) -.sp -int -\fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR) -.sp -int -\fBTcl_NRCallObjProc2\fR(\fIinterp, nreProc2, 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 -int -\fBTcl_NRExprObj\fR(\fIinterp, objPtr, resultPtr\fR) -.sp -void -\fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR) -.fi -.SH ARGUMENTS -.AS Tcl_CmdDeleteProc *interp in -.AP Tcl_Interp *interp in -The relevant Interpreter. -.AP "const char" *cmdName in -Name of the command to create. -.AP Tcl_ObjCmdProc *proc in -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_ObjCmdProc2 *proc2 in -Called in order to evaluate a command. Is often just a small wrapper that uses -\fBTcl_NRCallObjProc2\fR to call \fInreProc2\fR using a new trampoline. Behaves -in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3) -(\fIq.v.\fR). -.AP Tcl_ObjCmdProc *nreProc in -Called instead of \fIproc\fR when a trampoline is already in use. -.AP Tcl_ObjCmdProc2 *nreProc2 in -Called instead of \fIproc2\fR when a trampoline is already in use. -.AP ClientData clientData in -Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR -and \fIobjProc\fR. -.AP Tcl_CmdDeleteProc *deleteProc in/out -Called before \fIcmdName\fR is deleted from the interpreter, allowing for -command-specific cleanup. May be NULL. -.AP int objc in -Number of items in \fIobjv\fR. -.AP Tcl_Obj **objv in -Words in the command. -.AP Tcl_Obj *objPtr in -A script or expression to evaluate. -.AP int flags in -As described for \fITcl_EvalObjv\fR. -.PP -.AP Tcl_Command cmd in -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 the evaluation is stored if -the return code is TCL_OK. -.AP Tcl_NRPostProc *postProcPtr in -A function to push. -.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 -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_NRCreateCommand2\fR, is an alternative to \fBTcl_NRCreateCommand\fR -in the same way as \fBTcl_CreateObjCommand2\fR. -.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 -\fBTcl_NRPostProc\fR( - \fBClientData\fR \fIdata\fR[], - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIresult\fR); -.CE -.PP -\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 following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C -stack, to evalute a script: -.PP -.CS -int -\fITheCmdOldObjProc\fR( - ClientData clientData, - Tcl_Interp *interp, - int objc, - Tcl_Obj *const objv[]) -{ - int result; - Tcl_Obj *objPtr; - - \fI... preparation ...\fR - - result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0); - - \fI... postprocessing ...\fR - - return result; -} -\fBTcl_CreateObjCommand\fR(interp, "theCommand", - \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc); -.CE -.PP -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 -\fITheCmdOldObjProc\fR( - ClientData clientData, - Tcl_Interp *interp, - int objc, - Tcl_Obj *const objv[]) -{ - return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR, - clientData, objc, objv); -} -.CE -.PP -.CS -int -\fITheCmdNRObjProc\fR - ClientData clientData, - Tcl_Interp *interp, - int objc, - Tcl_Obj *const objv[]) -{ - Tcl_Obj *objPtr; - - \fI... preparation ...\fR - - \fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR, - data0, data1, data2, data3); - /* \fIdata0 .. data3\fR are up to four one-word items to - * pass to the postprocessing procedure */ - - return \fBTcl_NREvalObj\fR(interp, objPtr, 0); -} -.CE -.PP -.CS -int -\fITheCmdNRPostProc\fR( - ClientData data[], - Tcl_Interp *interp, - int result) -{ - /* \fIdata[0] .. data[3]\fR are the four words of data - * passed to \fBTcl_NRAddCallback\fR */ - - \fI... postprocessing ...\fR - - return result; -} -.CE -.PP -Any function comprising a routine can push other functions, making it possible -implement looping and sequencing constructs using the function stack. -.PP -.SH "REFERENCE COUNT MANAGEMENT" -.PP -The first \fIobjc\fR values in the \fIobjv\fR array passed to the functions -\fBTcl_NRCallObjProc\fR, \fBTcl_NREvalObjv\fR, and \fBTcl_NRCmdSwap\fR should -have a reference count of at least 1; they may have additional references -taken during the execution. -.PP -The \fIobjPtr\fR argument to \fBTcl_NREvalObj\fR and \fBTcl_NRExprObj\fR -should have a reference count of at least 1, and may have additional -references taken to it during execution. -.PP -The \fIresultObj\fR argument to \fBTcl_NRExprObj\fR should be an unshared -object. -.PP -Use \fBTcl_NRAddCallback\fR to schedule any required final decrementing of the -reference counts of arguments to any of the other functions on this page, as -with any other post-processing step in the non-recursive execution engine. -.PP -The -.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 \(co 2008 Kevin B. Kenny. -Copyright \(co 2018 Nathan Coulter. |