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
75                                                             either
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
86                                                             interpreter.
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
101                                                             indicates     how
102                                                             often a  particu‐
103                                                             lar  limit should
104                                                             really         be
105                                                             checked.  Must be
106                                                             at least 1.
107
108       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
135       ClientData clientData (in)                            Arbitrary
136                                                             pointer-sized
137                                                             word used to pass
138                                                             some  context  to
139                                                             the   handlerProc
140                                                             function.
141
142       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

DESCRIPTION

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
157       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
166       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
171       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

LIMIT CHECKING API

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

LIMIT CONFIGURATION

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
200       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
206       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
210   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
215              typedef void Tcl_LimitHandlerProc(
216                      ClientData clientData,
217                      Tcl_Interp *interp);
218
219       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
223       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
229              typedef void Tcl_LimitHandlerDeleteProc(
230                      ClientData clientData);
231
232       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

KEYWORDS

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