1NRE(3) Tcl Library Procedures NRE(3)
2
3
4
5______________________________________________________________________________
6
8 Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv,
9 Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stack‐
10 less) evaluation of Tcl scripts.
11
13 #include <tcl.h>
14
15 Tcl_Command
16 Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
17 deleteProc)
18
19 int
20 Tcl_NRCallObjProc(interp, nreProc, clientData, objc, objv)
21
22 int
23 Tcl_NREvalObj(interp, objPtr, flags)
24
25 int
26 Tcl_NREvalObjv(interp, objc, objv, flags)
27
28 int
29 Tcl_NRCmdSwap(interp, cmd, objc, objv, flags)
30
31 int
32 Tcl_NRExprObj(interp, objPtr, resultPtr)
33
34 void
35 Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)
36
38 Tcl_Interp *interp (in) The relevant Interpreter.
39
40 char *cmdName (in) Name of the command to create.
41
42 Tcl_ObjCmdProc *proc (in) Called in order to evaluate a
43 command. Is often just a small
44 wrapper that uses Tcl_NRCallOb‐
45 jProc to call nreProc using a
46 new trampoline. Behaves in the
47 same way as the proc argument
48 to Tcl_CreateObjCommand(3)
49 (q.v.).
50
51 Tcl_ObjCmdProc *nreProc (in) Called instead of proc when a
52 trampoline is already in use.
53
54 ClientData clientData (in) Arbitrary one-word value passed
55 to proc, nreProc, deleteProc
56 and objProc.
57
58 Tcl_CmdDeleteProc *deleteProc (in/out) Called before cmdName is
59 deleted from the interpreter,
60 allowing for command-specific
61 cleanup. May be NULL.
62
63 int objc (in) Number of items in objv.
64
65 Tcl_Obj **objv (in) Words in the command.
66
67 Tcl_Obj *objPtr (in) A script or expression to eval‐
68 uate.
69
70 int flags (in) As described for Tcl_EvalObjv.
71
72 Tcl_Command cmd (in) Token to use instead of one
73 derived from the first word of
74 objv in order to evaluate a
75 command.
76
77 Tcl_Obj *resultPtr (out) Pointer to an unshared Tcl_Obj
78 where the result of the evalua‐
79 tion is stored if the return
80 code is TCL_OK.
81
82 Tcl_NRPostProc *postProcPtr (in) A function to push.
83
84 ClientData data0 (in)
85
86 ClientData data1 (in)
87
88 ClientData data2 (in)
89
90 ClientData data3 (in) data0 through data3 are four
91 one-word values that will be
92 passed to the function desig‐
93 nated by postProcPtr when it is
94 invoked.
95______________________________________________________________________________
96
98 These functions provide an interface to the function stack that an
99 interpreter iterates through to evaluate commands. The routine behind
100 a command is implemented by an initial function and any additional
101 functions that the routine pushes onto the stack as it progresses. The
102 interpreter itself pushes functions onto the stack to react to the end
103 of a routine and to exercise other forms of control such as switching
104 between in-progress stacks and the evaluation of other scripts at addi‐
105 tional levels without adding frames to the C stack. To execute a rou‐
106 tine, the initial function for the routine is called and then a small
107 bit of code called a trampoline iteratively takes functions off the
108 stack and calls them, using the value of the last call as the value of
109 the routine.
110
111 Tcl_NRCallObjProc calls nreProc using a new trampoline.
112
113 Tcl_NRCreateCommand, an alternative to Tcl_CreateObjCommand, resolves
114 cmdName, which may contain namespace qualifiers, relative to the cur‐
115 rent namespace, creates a command by that name, and returns a token for
116 the command which may be used in subsequent calls to Tcl_GetCommand‐
117 Name. Except for a few cases noted below any existing command by the
118 same name is first deleted. If interp is in the process of being
119 deleted Tcl_NRCreateCommand does not create any command, does not
120 delete any command, and returns NULL.
121
122 Tcl_NREvalObj pushes a function that is like Tcl_EvalObjEx but consumes
123 no space on the C stack.
124
125 Tcl_NREvalObjv pushes a function that is like Tcl_EvalObjv but consumes
126 no space on the C stack.
127
128 Tcl_NRCmdSwap is like Tcl_NREvalObjv, but uses cmd, a token previously
129 returned by Tcl_CreateObjCommand or Tcl_GetCommandFromObj, instead of
130 resolving the first word of objv.
131
132 Tcl_NRExprObj pushes a function that evaluates objPtr as an expression
133 in the same manner as Tcl_ExprObj but without consuming space on the C
134 stack.
135
136 All of the functions return TCL_OK if the evaluation of the script,
137 command, or expression has been scheduled successfully. Otherwise (for
138 example if the command name cannot be resolved), they return TCL_ERROR
139 and store a message as the interpreter's result.
140
141 Tcl_NRAddCallback pushes postProcPtr. The signature for Tcl_NRPostProc
142 is:
143
144 typedef int
145 Tcl_NRPostProc(
146 ClientData data[],
147 Tcl_Interp *interp,
148 int result);
149
150 data is a pointer to an array containing data0 through data3. result
151 is the value returned by the previous function implementing part the
152 routine.
153
155 The following command uses Tcl_EvalObjEx, which consumes space on the C
156 stack, to evalute a script:
157
158 int
159 TheCmdOldObjProc(
160 ClientData clientData,
161 Tcl_Interp *interp,
162 int objc,
163 Tcl_Obj *const objv[])
164 {
165 int result;
166 Tcl_Obj *objPtr;
167
168 ... preparation ...
169
170 result = Tcl_EvalObjEx(interp, objPtr, 0);
171
172 ... postprocessing ...
173
174 return result;
175 }
176 Tcl_CreateObjCommand(interp, "theCommand",
177 TheCmdOldObjProc, clientData, TheCmdDeleteProc);
178
179 To avoid consuming space on the C stack, TheCmdOldObjProc is renamed to
180 TheCmdNRObjProc and the postprocessing step is split into a separate
181 function, TheCmdPostProc, which is pushed onto the function stack.
182 Tcl_EvalObjEx is replaced with Tcl_NREvalObj, which uses a trampoline
183 instead of consuming space on the C stack. A new version of TheCm‐
184 dOldObjProc is just a a wrapper that uses Tcl_NRCallObjProc to call
185 TheCmdNRObjProc:
186
187 int
188 TheCmdOldObjProc(
189 ClientData clientData,
190 Tcl_Interp *interp,
191 int objc,
192 Tcl_Obj *const objv[])
193 {
194 return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
195 clientData, objc, objv);
196 }
197
198 int
199 TheCmdNRObjProc
200 ClientData clientData,
201 Tcl_Interp *interp,
202 int objc,
203 Tcl_Obj *const objv[])
204 {
205 Tcl_Obj *objPtr;
206
207 ... preparation ...
208
209 Tcl_NRAddCallback(interp, TheCmdPostProc,
210 data0, data1, data2, data3);
211 /* data0 .. data3 are up to four one-word items to
212 * pass to the postprocessing procedure */
213
214 return Tcl_NREvalObj(interp, objPtr, 0);
215 }
216
217 int
218 TheCmdNRPostProc(
219 ClientData data[],
220 Tcl_Interp *interp,
221 int result)
222 {
223 /* data[0] .. data[3] are the four words of data
224 * passed to Tcl_NRAddCallback */
225
226 ... postprocessing ...
227
228 return result;
229 }
230
231 Any function comprising a routine can push other functions, making it
232 possible implement looping and sequencing constructs using the function
233 stack.
234
236 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3),
237 Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
238
240 stackless, nonrecursive, execute, command, global, value, result,
241 script
242
244 Copyright (c) 2008 by Kevin B. Kenny. Copyright (c) 2018 by Nathan
245 Coulter.
246
247
248
249Tcl 8.6 NRE(3)