NRE(3tcl) Tcl Library Procedures NRE(3tcl)
______________________________________________________________________________
NAME
Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv,
Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stack-
less) evaluation of Tcl scripts.
SYNOPSIS
#include <tcl.h>
Tcl_Command
Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
deleteProc)
int
Tcl_NRCallObjProc(interp, nreProc, 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)
void
Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)
ARGUMENTS
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_NRCallOb-
jProc to call nreProc using a
new trampoline. Behaves in the
same way as the proc argument
to Tcl_CreateObjCommand(3tcl)
(q.v.).
Tcl_ObjCmdProc *nreProc (in) Called instead of proc when a
trampoline is already in use.
ClientData 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.
int objc (in) Number of items in objv.
Tcl_Obj **objv (in) Words in the command.
Tcl_Obj *objPtr (in) A script or expression to eval-
uate.
int flags (in) As described for Tcl_EvalObjv.
Tcl_Command cmd (in) Token to use instead of one de-
rived 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 evalua-
tion is stored if the return
code is TCL_OK.
Tcl_NRPostProc *postProcPtr (in) A function to push.
ClientData data0 (in)
ClientData data1 (in)
ClientData data2 (in)
ClientData data3 (in) data0 through data3 are four
one-word values that will be
passed to the function desig-
nated by postProcPtr when it is
invoked.
______________________________________________________________________________
DESCRIPTION
These functions provide an interface to the function stack that an in-
terpreter iterates through to evaluate commands. The routine behind a
command is implemented by an initial function and any additional func-
tions that the routine pushes onto the stack as it progresses. The in-
terpreter itself pushes functions onto the stack to react to the end of
a routine and to exercise other forms of control such as switching be-
tween in-progress stacks and the evaluation of other scripts at addi-
tional levels without adding frames to the C stack. To execute a rou-
tine, 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 cur-
rent namespace, creates a command by that name, and returns a token for
the command which may be used in subsequent calls to Tcl_GetCommand-
Name. 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_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(
ClientData 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.
EXAMPLE
The following command uses Tcl_EvalObjEx, which consumes space on the C
stack, to evalute a script:
int
TheCmdOldObjProc(
ClientData 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 TheCm-
dOldObjProc is just a a wrapper that uses Tcl_NRCallObjProc to call
TheCmdNRObjProc:
int
TheCmdOldObjProc(
ClientData clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[])
{
return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
clientData, objc, objv);
}
int
TheCmdNRObjProc
ClientData 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(
ClientData 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.
SEE ALSO
Tcl_CreateCommand(3tcl), Tcl_CreateObjCommand(3tcl), Tcl_EvalOb-
jEx(3tcl), Tcl_GetCommandFromObj(3tcl), Tcl_ExprObj(3tcl)
KEYWORDS
stackless, nonrecursive, execute, command, global, value, result,
script
COPYRIGHT
Copyright © 2008 Kevin B. Kenny. Copyright © 2018 Nathan Coulter.
Tcl 8.6 NRE(3tcl)
Generated by dwww version 1.14 on Thu Jan 23 01:12:39 CET 2025.