![]() |
![]()
| ![]() |
![]()
NAMETcl_NRCreateCommand, Tcl_NRCreateCommand2, Tcl_NRCallObjProc, Tcl_NRCallObjProc2, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stackless) evaluation of Tcl scripts. SYNOPSIS#include <tcl.h> Tcl_Command Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData, ARGUMENTS
DESCRIPTIONThese 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 trampoline iteratively takes functions off the stack and calls them, using the value of the last call as the value of the routine. Tcl_NRCallObjProc calls nreProc using a new trampoline. Tcl_NRCreateCommand, an alternative to Tcl_CreateObjCommand, resolves cmdName, 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 Tcl_GetCommandName. Except for a few cases noted below any existing command by the same name is first deleted. If interp is in the process of being deleted Tcl_NRCreateCommand does not create any command, does not delete any command, and returns NULL. Tcl_NRCreateCommand2, is an alternative to Tcl_NRCreateCommand in the same way as Tcl_CreateObjCommand2. Tcl_NREvalObj pushes a function that is like Tcl_EvalObjEx but consumes no space on the C stack. Tcl_NREvalObjv pushes a function that is like Tcl_EvalObjv but consumes no space on the C stack. Tcl_NRCmdSwap is like Tcl_NREvalObjv, but uses cmd, a token previously returned by Tcl_CreateObjCommand or Tcl_GetCommandFromObj, instead of resolving the first word of objv. Tcl_NRExprObj pushes a function that evaluates objPtr as an expression in the same manner as Tcl_ExprObj but without consuming space on the C stack. All of the functions return TCL_OK 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 TCL_ERROR and store a message as the interpreter's result. Tcl_NRAddCallback pushes postProcPtr. The signature for Tcl_NRPostProc is: typedef int Tcl_NRPostProc( data is a pointer to an array containing data0 through data3. result is the value returned by the previous function implementing part the routine. EXAMPLEThe following command uses Tcl_EvalObjEx, which consumes space on the C stack, to evaluate a script: int TheCmdOldObjProc( To avoid consuming space on the C stack, TheCmdOldObjProc is renamed to TheCmdNRObjProc and the postprocessing step is split into a separate function, TheCmdPostProc, which is pushed onto the function stack. Tcl_EvalObjEx is replaced with Tcl_NREvalObj, which uses a trampoline instead of consuming space on the C stack. A new version of TheCmdOldObjProc is just a a wrapper that uses Tcl_NRCallObjProc to call TheCmdNRObjProc: int TheCmdOldObjProc( int TheCmdNRObjProc int TheCmdNRPostProc( Any function comprising a routine can push other functions, making it possible implement looping and sequencing constructs using the function stack. REFERENCE COUNT MANAGEMENTThe first objc values in the objv array passed to the functions Tcl_NRCallObjProc, Tcl_NREvalObjv, and Tcl_NRCmdSwap should have a reference count of at least 1; they may have additional references taken during the execution. The objPtr argument to Tcl_NREvalObj and Tcl_NRExprObj should have a reference count of at least 1, and may have additional references taken to it during execution. The resultObj argument to Tcl_NRExprObj should be an unshared object. Use Tcl_NRAddCallback 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. The SEE ALSOTcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3) KEYWORDSstackless, nonrecursive, execute, command, global, value, result, script COPYRIGHTCopyright © 2008 Kevin B. Kenny. Copyright © 2018 Nathan Coulter.
|