- 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.
- SYNOPSIS
- #include <tcl.h>
- Tcl_Command
- Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
- deleteProc
)
- Tcl_Command
- Tcl_NRCreateCommand2(interp, cmdName, proc2, nreProc2, clientData,
- deleteProc
)
- int
- Tcl_NRCallObjProc(interp, nreProc, clientData, objc, objv)
- int
- Tcl_NRCallObjProc2(interp, nreProc2, clientData, objc, objv)
- int
- Tcl_NREvalObj(interp, objPtr, flags)
- int
- Tcl_NREvalObjv(interp, objc, objv, flags)
- int
- Tcl_NRCmdSwap(interp, cmd, objc, objv, flags)
- int
- Tcl_NRExprObj(interp, objPtr, resultPtr)
- Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)
- ARGUMENTS
- DESCRIPTION
- EXAMPLE
- REFERENCE COUNT MANAGEMENT
- SEE ALSO
- KEYWORDS
- COPYRIGHT
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.
#include <tcl.h>
Tcl_Command
Tcl_NRCreateCommand(
interp, cmdName, proc, nreProc, clientData,
deleteProc)
Tcl_Command
Tcl_NRCreateCommand2(
interp, cmdName, proc2, nreProc2, clientData,
deleteProc)
int
Tcl_NRCallObjProc(
interp, nreProc, clientData, objc, objv)
int
Tcl_NRCallObjProc2(
interp, nreProc2, clientData, objc, objv)
int
Tcl_NREvalObj(
interp, objPtr, flags)
int
Tcl_NREvalObjv(
interp, objc, objv, flags)
int
Tcl_NRCmdSwap(
interp, cmd, objc, objv, flags)
int
Tcl_NRExprObj(
interp, objPtr, resultPtr)
Tcl_NRAddCallback(
interp, postProcPtr, data0, data1, data2, data3)
- Tcl_Interp *interp (in)
-
The relevant Interpreter.
- const char *cmdName (in)
-
Name of the command to create.
- Tcl_ObjCmdProc *proc (in)
-
Called in order to evaluate a command. Is often just a small wrapper that uses
Tcl_NRCallObjProc to call nreProc using a new trampoline. Behaves
in the same way as the proc argument to Tcl_CreateObjCommand(3)
(q.v.).
- Tcl_ObjCmdProc2 *proc2 (in)
-
Called in order to evaluate a command. Is often just a small wrapper that uses
Tcl_NRCallObjProc2 to call nreProc2 using a new trampoline. Behaves
in the same way as the proc2 argument to Tcl_CreateObjCommand2(3)
(q.v.).
- Tcl_ObjCmdProc *nreProc (in)
-
Called instead of proc when a trampoline is already in use.
- Tcl_ObjCmdProc2 *nreProc2 (in)
-
Called instead of proc2 when a trampoline is already in use.
- void *clientData (in)
-
Arbitrary one-word value passed to proc, nreProc, deleteProc
and objProc.
- Tcl_CmdDeleteProc *deleteProc (in/out)
-
Called before cmdName is deleted from the interpreter, allowing for
command-specific cleanup. May be NULL.
- Tcl_Size objc (in)
-
Number of items in objv.
- Tcl_Obj **objv (in)
-
Words in the command.
- Tcl_Obj *objPtr (in)
-
A script or expression to evaluate.
- int flags (in)
-
As described for Tcl_EvalObjv.
- Tcl_Command cmd (in)
-
Token to use instead of one derived from the first word of objv in order
to evaluate a command.
- 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.
- Tcl_NRPostProc *postProcPtr (in)
-
A function to push.
- void *data0 (in)
-
- void *data1 (in)
-
- void *data2 (in)
-
- void *data3 (in)
-
data0 through data3 are four one-word values that will be passed
to the function designated by postProcPtr when it is invoked.
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
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(
void * data[],
Tcl_Interp *interp,
int result);
data is a pointer to an array containing data0 through data3.
result is the value returned by the previous function implementing part
the routine.
The following command uses
Tcl_EvalObjEx, which consumes space on the C
stack, to evaluate a script:
int
TheCmdOldObjProc(
void *clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[])
{
int result;
Tcl_Obj *objPtr;
... preparation ...
result = Tcl_EvalObjEx(interp, objPtr, 0);
... postprocessing ...
return result;
}
Tcl_CreateObjCommand(interp, "theCommand",
TheCmdOldObjProc, clientData, TheCmdDeleteProc);
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(
void *clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[])
{
return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
clientData, objc, objv);
}
int
TheCmdNRObjProc
void *clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[])
{
Tcl_Obj *objPtr;
... preparation ...
Tcl_NRAddCallback(interp, TheCmdPostProc,
data0, data1, data2, data3);
/* data0 .. data3 are up to four one-word items to
* pass to the postprocessing procedure */
return Tcl_NREvalObj(interp, objPtr, 0);
}
int
TheCmdNRPostProc(
void *data[],
Tcl_Interp *interp,
int result)
{
/* data[0] .. data[3] are the four words of data
* passed to Tcl_NRAddCallback */
... postprocessing ...
return result;
}
Any function comprising a routine can push other functions, making it possible
implement looping and sequencing constructs using the function stack.
The 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
Tcl_CreateCommand,
Tcl_CreateObjCommand,
Tcl_EvalObjEx,
Tcl_GetCommandFromObj,
Tcl_ExprObj
stackless,
nonrecursive,
execute,
command,
global,
value,
result,
script
Copyright © 2008 Kevin B. Kenny.
Copyright © 2018 Nathan Coulter.