NRE(3) Tcl Library Procedures NRE(3) ______________________________________________________________________________
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.
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(3)
(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
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 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
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 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(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3),
Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
KEYWORDS
stackless, nonrecursive, execute, command, global, value, result,
script
COPYRIGHT
Copyright (c) 2008 by Kevin B. Kenny. Copyright (c) 2018 by Nathan
Coulter.
Tcl 8.6 NRE(3)
tcl 8.6.9 - Generated Fri Nov 16 19:28:29 CST 2018