1Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
2______________________________________________________________________________
6
8 Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded, Tcl_LimitGet‐
9 Commands, Tcl_LimitGetGranularity, Tcl_LimitGetTime, Tcl_LimitReady,
10 Tcl_LimitRemoveHandler, Tcl_LimitSetCommands, Tcl_LimitSetGranularity,
11 Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeExceeded,
12 Tcl_LimitTypeReset, Tcl_LimitTypeSet - manage and check resource limits
13 on interpreters
14
16 #include <tcl.h>
17 int
19 Tcl_LimitCheck(interp)
20 int
22 Tcl_LimitReady(interp)
23 int
25 Tcl_LimitExceeded(interp)
26 int
28 Tcl_LimitTypeExceeded(interp, type)
29 int
31 Tcl_LimitTypeEnabled(interp, type)
32 void
34 Tcl_LimitTypeSet(interp, type)
35 void
37 Tcl_LimitTypeReset(interp, type)
38 int
40 Tcl_LimitGetCommands(interp)
41 void
43 Tcl_LimitSetCommands(interp, commandLimit)
44 void
46 Tcl_LimitGetTime(interp, timeLimitPtr)
47 void
49 Tcl_LimitSetTime(interp, timeLimitPtr)
50 int
52 Tcl_LimitGetGranularity(interp, type)
53 void
55 Tcl_LimitSetGranularity(interp, type, granularity)
56 void
58 Tcl_LimitAddHandler(interp, type, handlerProc, clientData, deleteProc)
59 void
61 Tcl_LimitRemoveHandler(interp, type, handlerProc, clientData)
62
64 Tcl_Interp *interp (in) Interpreter that
65 the limit being
66 managed applies
67 to or that will
68 have its limits
69 checked.
70 int type (in) The type of limit
72 that the opera‐
73 tion refers to.
74 This must be
75 either
76 TCL_LIMIT_COM‐
77 MANDS or
78 TCL_LIMIT_TIME.
79 int commandLimit (in) The maximum num‐
81 ber of commands
82 (as reported by
83 info cmdcount)
84 that may be exe‐
85 cuted in the
86 interpreter.
87 Tcl_Time *timeLimitPtr (in/out) A pointer to a
89 structure that
90 will either have
91 the new time
92 limit read from
93 (Tcl_LimitSet‐
94 Time) or the cur‐
95 rent time limit
96 written to
97 (Tcl_LimitGet‐
98 Time).
99 int granularity (in) Divisor that
101 indicates how
102 often a particu‐
103 lar limit should
104 really be
105 checked. Must be
106 at least 1.
107 Tcl_LimitHandlerProc *handlerProc (in) Function to call
109 when a particular
110 limit is
111 exceeded. If the
112 handlerProc
113 removes or raises
114 the limit during
115 its processing,
116 the limited
117 interpreter will
118 be permitted to
119 continue to
120 process after the
121 handler returns.
122 Many handlers may
123 be attached to
124 the same inter‐
125 preter limit;
126 their order of
127 execution is not
128 defined, and they
129 must be identi‐
130 fied by handler‐
131 Proc and client‐
132 Data when they
133 are deleted.
134 ClientData clientData (in) Arbitrary
136 pointer-sized
137 word used to pass
138 some context to
139 the handlerProc
140 function.
141 Tcl_LimitHandlerDeleteProc *deleteProc (in) Function to call
143 whenever a han‐
144 dler is deleted.
145 May be NULL if
146 the clientData
147 requires no dele‐
148 tion.
149______________________________________________________________________________
150
152 Tcl's interpreter resource limit subsystem allows for close control
153 over how much computation time a script may use, and is useful for
154 cases where a program is divided into multiple pieces where some parts
155 are more trusted than others (e.g. web application servers).
156 Every interpreter may have a limit on the wall-time for execution, and
158 a limit on the number of commands that the interpreter may execute.
159 Since checking of these limits is potentially expensive (especially the
160 time limit), each limit also has a checking granularity, which is a
161 divisor for an internal count of the number of points in the core where
162 a check may be performed (which is immediately before executing a com‐
163 mand and at an unspecified frequency between running commands, which
164 can happen in empty-bodied while loops).
165 The final component of the limit engine is a callback scheme which
167 allows for notifications of when a limit has been exceeded. These
168 callbacks can just provide logging, or may allocate more resources to
169 the interpreter to permit it to continue processing longer.
170 When a limit is exceeded (and the callbacks have run; the order of exe‐
172 cution of the callbacks is unspecified) execution in the limited inter‐
173 preter is stopped by raising an error and setting a flag that prevents
174 the catch command in that interpreter from trapping that error. It is
175 up to the context that started execution in that interpreter (typically
176 a master interpreter) to handle the error.
177
179 To check the resource limits for an interpreter, call Tcl_LimitCheck,
180 which returns TCL_OK if the limit was not exceeded (after processing
181 callbacks) and TCL_ERROR if the limit was exceeded (in which case an
182 error message is also placed in the interpreter result). That function
183 should only be called when Tcl_LimitReady returns non-zero so that
184 granularity policy is enforced. This API is designed to be similar in
185 usage to Tcl_AsyncReady and Tcl_AsyncInvoke.
186 When writing code that may behave like catch in respect of errors, you
188 should only trap an error if Tcl_LimitExceeded returns zero. If it
189 returns non-zero, the interpreter is in a limit-exceeded state and
190 errors should be allowed to propagate to the calling context. You can
191 also check whether a particular type of limit has been exceeded using
192 Tcl_LimitTypeExceeded.
193
195 To check whether a limit has been set (but not whether it has actually
196 been exceeded) on an interpreter, call Tcl_LimitTypeEnabled with the
197 type of limit you want to check. To enable a particular limit call
198 Tcl_LimitTypeSet, and to disable a limit call Tcl_LimitTypeReset.
199 The level of a command limit may be set using Tcl_LimitSetCommands, and
201 retrieved using Tcl_LimitGetCommands. Similarly for a time limit with
202 Tcl_LimitSetTime and Tcl_LimitGetTime respectively, but with that API
203 the time limit is copied from and to the Tcl_Time structure that the
204 timeLimitPtr argument points to.
205 The checking granularity for a particular limit may be set using
207 Tcl_LimitSetGranularity and retrieved using Tcl_LimitGetGranularity.
208 Note that granularities must always be positive.
209 LIMIT CALLBACKS
211 To add a handler callback to be invoked when a limit is exceeded, call
212 Tcl_LimitAddHandler. The handlerProc argument describes the function
213 that will actually be called; it should have the following prototype:
214 typedef void Tcl_LimitHandlerProc(
216 ClientData clientData,
217 Tcl_Interp *interp);
218 The clientData argument to the handler will be whatever is passed to
220 the clientData argument to Tcl_LimitAddHandler, and the interp is the
221 interpreter that had its limit exceeded.
222 The deleteProc argument to Tcl_LimitAddHandler is a function to call to
224 delete the clientData value. It may be TCL_STATIC or NULL if no dele‐
225 tion action is necessary, or TCL_DYNAMIC if all that is necessary is to
226 free the structure with Tcl_Free. Otherwise, it should refer to a
227 function with the following prototype:
228 typedef void Tcl_LimitHandlerDeleteProc(
230 ClientData clientData);
231 A limit handler may be deleted using Tcl_LimitRemoveHandler; the han‐
233 dler removed will be the first one found (out of the handlers added
234 with Tcl_LimitAddHandler) with exactly matching type, handlerProc and
235 clientData arguments. This function always invokes the deleteProc on
236 the clientData (unless the deleteProc was NULL or TCL_STATIC).
237
239 interpreter, resource, limit, commands, time, callback
240Tcl 8.5 Tcl_LimitCheck(3)