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 ei‐
75 ther
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 in‐
86 terpreter.
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 in‐
101 dicates how often
102 a particular
103 limit should re‐
104 ally be checked.
105 Must be at least
106 1.
107 Tcl_LimitHandlerProc *handlerProc (in) Function to call
109 when a particular
110 limit is ex‐
111 ceeded. If the
112 handlerProc re‐
113 moves or raises
114 the limit during
115 its processing,
116 the limited in‐
117 terpreter will be
118 permitted to con‐
119 tinue to process
120 after the handler
121 returns. Many
122 handlers may be
123 attached to the
124 same interpreter
125 limit; their or‐
126 der of execution
127 is not defined,
128 and they must be
129 identified by
130 handlerProc and
131 clientData when
132 they are deleted.
133 ClientData clientData (in) Arbitrary
135 pointer-sized
136 word used to pass
137 some context to
138 the handlerProc
139 function.
140 Tcl_LimitHandlerDeleteProc *deleteProc (in) Function to call
142 whenever a han‐
143 dler is deleted.
144 May be NULL if
145 the clientData
146 requires no dele‐
147 tion.
148______________________________________________________________________________
149
151 Tcl's interpreter resource limit subsystem allows for close control
152 over how much computation time a script may use, and is useful for
153 cases where a program is divided into multiple pieces where some parts
154 are more trusted than others (e.g. web application servers).
155 Every interpreter may have a limit on the wall-time for execution, and
157 a limit on the number of commands that the interpreter may execute.
158 Since checking of these limits is potentially expensive (especially the
159 time limit), each limit also has a checking granularity, which is a di‐
160 visor for an internal count of the number of points in the core where a
161 check may be performed (which is immediately before executing a command
162 and at an unspecified frequency between running commands, which can
163 happen in empty-bodied while loops).
164 The final component of the limit engine is a callback scheme which al‐
166 lows for notifications of when a limit has been exceeded. These call‐
167 backs can just provide logging, or may allocate more resources to the
168 interpreter to permit it to continue processing longer.
169 When a limit is exceeded (and the callbacks have run; the order of exe‐
171 cution of the callbacks is unspecified) execution in the limited inter‐
172 preter is stopped by raising an error and setting a flag that prevents
173 the catch command in that interpreter from trapping that error. It is
174 up to the context that started execution in that interpreter (typically
175 the main interpreter) to handle the error.
176
178 To check the resource limits for an interpreter, call Tcl_LimitCheck,
179 which returns TCL_OK if the limit was not exceeded (after processing
180 callbacks) and TCL_ERROR if the limit was exceeded (in which case an
181 error message is also placed in the interpreter result). That function
182 should only be called when Tcl_LimitReady returns non-zero so that
183 granularity policy is enforced. This API is designed to be similar in
184 usage to Tcl_AsyncReady and Tcl_AsyncInvoke.
185 When writing code that may behave like catch in respect of errors, you
187 should only trap an error if Tcl_LimitExceeded returns zero. If it re‐
188 turns non-zero, the interpreter is in a limit-exceeded state and errors
189 should be allowed to propagate to the calling context. You can also
190 check whether a particular type of limit has been exceeded using
191 Tcl_LimitTypeExceeded.
192
194 To check whether a limit has been set (but not whether it has actually
195 been exceeded) on an interpreter, call Tcl_LimitTypeEnabled with the
196 type of limit you want to check. To enable a particular limit call
197 Tcl_LimitTypeSet, and to disable a limit call Tcl_LimitTypeReset.
198 The level of a command limit may be set using Tcl_LimitSetCommands, and
200 retrieved using Tcl_LimitGetCommands. Similarly for a time limit with
201 Tcl_LimitSetTime and Tcl_LimitGetTime respectively, but with that API
202 the time limit is copied from and to the Tcl_Time structure that the
203 timeLimitPtr argument points to.
204 The checking granularity for a particular limit may be set using
206 Tcl_LimitSetGranularity and retrieved using Tcl_LimitGetGranularity.
207 Note that granularities must always be positive.
208 LIMIT CALLBACKS
210 To add a handler callback to be invoked when a limit is exceeded, call
211 Tcl_LimitAddHandler. The handlerProc argument describes the function
212 that will actually be called; it should have the following prototype:
213 typedef void Tcl_LimitHandlerProc(
215 ClientData clientData,
216 Tcl_Interp *interp);
217 The clientData argument to the handler will be whatever is passed to
219 the clientData argument to Tcl_LimitAddHandler, and the interp is the
220 interpreter that had its limit exceeded.
221 The deleteProc argument to Tcl_LimitAddHandler is a function to call to
223 delete the clientData value. It may be TCL_STATIC or NULL if no dele‐
224 tion action is necessary, or TCL_DYNAMIC if all that is necessary is to
225 free the structure with Tcl_Free. Otherwise, it should refer to a
226 function with the following prototype:
227 typedef void Tcl_LimitHandlerDeleteProc(
229 ClientData clientData);
230 A limit handler may be deleted using Tcl_LimitRemoveHandler; the han‐
232 dler removed will be the first one found (out of the handlers added
233 with Tcl_LimitAddHandler) with exactly matching type, handlerProc and
234 clientData arguments. This function always invokes the deleteProc on
235 the clientData (unless the deleteProc was NULL or TCL_STATIC).
236
238 interpreter, resource, limit, commands, time, callback
239Tcl 8.5 Tcl_LimitCheck(3)