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
153 Tcl's interpreter resource limit subsystem allows for close control
154 over how much computation time a script may use, and is useful for
155 cases where a program is divided into multiple pieces where some parts
156 are more trusted than others (e.g. web application servers).
157 Every interpreter may have a limit on the wall-time for execution, and
159 a limit on the number of commands that the interpreter may execute.
160 Since checking of these limits is potentially expensive (especially the
161 time limit), each limit also has a checking granularity, which is a
162 divisor for an internal count of the number of points in the core where
163 a check may be performed (which is immediately before executing a com‐
164 mand and at an unspecified frequency between running commands, which
165 can happen in empty-bodied while loops).
166 The final component of the limit engine is a callback scheme which
168 allows for notifications of when a limit has been exceeded. These
169 callbacks can just provide logging, or may allocate more resources to
170 the interpreter to permit it to continue processing longer.
171 When a limit is exceeded (and the callbacks have run; the order of exe‐
173 cution of the callbacks is unspecified) execution in the limited inter‐
174 preter is stopped by raising an error and setting a flag that prevents
175 the catch command in that interpreter from trapping that error. It is
176 up to the context that started execution in that interpreter (typically
177 a master interpreter) to handle the error.
178
180 To check the resource limits for an interpreter, call Tcl_LimitCheck,
181 which returns TCL_OK if the limit was not exceeded (after processing
182 callbacks) and TCL_ERROR if the limit was exceeded (in which case an
183 error message is also placed in the interpreter result). That function
184 should only be called when Tcl_LimitReady returns non-zero so that
185 granularity policy is enforced. This API is designed to be similar in
186 usage to Tcl_AsyncReady and Tcl_AsyncInvoke.
187 When writing code that may behave like catch in respect of errors, you
189 should only trap an error if Tcl_LimitExceeded returns zero. If it
190 returns non-zero, the interpreter is in a limit-exceeded state and
191 errors should be allowed to propagate to the calling context. You can
192 also check whether a particular type of limit has been exceeded using
193 Tcl_LimitTypeExceeded.
194
196 To check whether a limit has been set (but not whether it has actually
197 been exceeded) on an interpreter, call Tcl_LimitTypeEnabled with the
198 type of limit you want to check. To enable a particular limit call
199 Tcl_LimitTypeSet, and to disable a limit call Tcl_LimitTypeReset.
200 The level of a command limit may be set using Tcl_LimitSetCommands, and
202 retrieved using Tcl_LimitGetCommands. Similarly for a time limit with
203 Tcl_LimitSetTime and Tcl_LimitGetTime respectively, but with that API
204 the time limit is copied from and to the Tcl_Time structure that the
205 timeLimitPtr argument points to.
206 The checking granularity for a particular limit may be set using
208 Tcl_LimitSetGranularity and retrieved using Tcl_LimitGetGranularity.
209 Note that granularities must always be positive.
210 LIMIT CALLBACKS
212 To add a handler callback to be invoked when a limit is exceeded, call
213 Tcl_LimitAddHandler. The handlerProc argument describes the function
214 that will actually be called; it should have the following prototype:
215 typedef void Tcl_LimitHandlerProc(
217 ClientData clientData,
218 Tcl_Interp *interp);
219 The clientData argument to the handler will be whatever is passed to
221 the clientData argument to Tcl_LimitAddHandler, and the interp is the
222 interpreter that had its limit exceeded.
223 The deleteProc argument to Tcl_LimitAddHandler is a function to call to
225 delete the clientData value. It may be TCL_STATIC or NULL if no dele‐
226 tion action is necessary, or TCL_DYNAMIC if all that is necessary is to
227 free the structure with Tcl_Free. Otherwise, it should refer to a
228 function with the following prototype:
229 typedef void Tcl_LimitHandlerDeleteProc(
231 ClientData clientData);
232 A limit handler may be deleted using Tcl_LimitRemoveHandler; the han‐
234 dler removed will be the first one found (out of the handlers added
235 with Tcl_LimitAddHandler) with exactly matching type, handlerProc and
236 clientData arguments. This function always invokes the deleteProc on
237 the clientData (unless the deleteProc was NULL or TCL_STATIC).
238
241 interpreter, resource, limit, commands, time, callback
242Tcl 8.5 Tcl_LimitCheck(3)