1Tcl_LimitCheck(3)           Tcl Library Procedures           Tcl_LimitCheck(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

16       #include <tcl.h>
17
18       int
19       Tcl_LimitCheck(interp)
20
21       int
22       Tcl_LimitReady(interp)
23
24       int
25       Tcl_LimitExceeded(interp)
26
27       int
28       Tcl_LimitTypeExceeded(interp, type)
29
30       int
31       Tcl_LimitTypeEnabled(interp, type)
32
33       void
34       Tcl_LimitTypeSet(interp, type)
35
36       void
37       Tcl_LimitTypeReset(interp, type)
38
39       int
40       Tcl_LimitGetCommands(interp)
41
42       void
43       Tcl_LimitSetCommands(interp, commandLimit)
44
45       void
46       Tcl_LimitGetTime(interp, timeLimitPtr)
47
48       void
49       Tcl_LimitSetTime(interp, timeLimitPtr)
50
51       int
52       Tcl_LimitGetGranularity(interp, type)
53
54       void
55       Tcl_LimitSetGranularity(interp, type, granularity)
56
57       void
58       Tcl_LimitAddHandler(interp, type, handlerProc, clientData, deleteProc)
59
60       void
61       Tcl_LimitRemoveHandler(interp, type, handlerProc, clientData)
62

ARGUMENTS

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
71       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
80       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
88       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
100       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
108       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
134       ClientData clientData (in)                            Arbitrary
135                                                             pointer-sized
136                                                             word used to pass
137                                                             some  context  to
138                                                             the   handlerProc
139                                                             function.
140
141       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

DESCRIPTION

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
156       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
165       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
170       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

LIMIT CHECKING API

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
186       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

LIMIT CONFIGURATION

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
199       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
205       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
209   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
214              typedef void Tcl_LimitHandlerProc(
215                      ClientData clientData,
216                      Tcl_Interp *interp);
217
218       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
222       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
228              typedef void Tcl_LimitHandlerDeleteProc(
229                      ClientData clientData);
230
231       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

KEYWORDS

238       interpreter, resource, limit, commands, time, callback
239
240
241
242Tcl                                   8.5                    Tcl_LimitCheck(3)
Impressum