|
|
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3) _________________________________________________________________
Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded,
Tcl_LimitGetCommands, Tcl_LimitGetGranularity,
Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler,
Tcl_LimitSetCommands, Tcl_LimitSetGranularity,
Tcl_LimitSetTime, Tcl_LimitTypeEnabled,
Tcl_LimitTypeExceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet
- manage and check resource limits on interpreters
#include <tcl.h>
int
Tcl_LimitCheck(interp)
int
Tcl_LimitReady(interp)
int
Tcl_LimitExceeded(interp)
int
Tcl_LimitTypeExceeded(interp, type)
int
Tcl_LimitTypeEnabled(interp, type)
void
Tcl_LimitTypeSet(interp, type)
void
Tcl_LimitTypeReset(interp, type)
int
Tcl_LimitGetCommands(interp)
void
Tcl_LimitSetCommands(interp, commandLimit)
void
Tcl_LimitGetTime(interp, timeLimitPtr)
void
Tcl_LimitSetTime(interp, timeLimitPtr)
int
Tcl_LimitGetGranularity(interp, type)
void
Tcl_LimitSetGranularity(interp, type, granularity)
Tcl Last change: 8.5 1
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
void
Tcl_LimitAddHandler(interp, type, handlerProc, clientData, deleteProc)
void
Tcl_LimitRemoveHandler(interp, type, handlerProc, clientData)
Tcl_Interp *interp (in) Interpreter
that
the
limit
being
managed
applies
to or
that
will
have
its
limits
checked.
int type (in) The
type
of
limit
that
the
opera-
tion
refers
to.
This
must
be
either
TCL_LIMIT_COMMANDS
or
TCL_LIMIT_TIME.
int commandLimit (in) The
max-
imum
number
of
com-
mands
(as
reported
by
info
cmdcount)
Tcl Last change: 8.5 2
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
that
may be
exe-
cuted
in the
inter-
preter.
Tcl_Time *timeLimitPtr (in/out) A
pointer
to a
struc-
ture
that
will
either
have
the
new
time
limit
read
from
(Tcl_LimitSetTime)
or the
current
time
limit
writ-
ten to
(Tcl_LimitGetTime).
int granularity (in) Divisor
that
indi-
cates
how
often
a par-
ticu-
lar
limit
should
really
be
checked.
Must
be at
least
1.
Tcl_LimitHandlerProc *handlerProc (in) Function
Tcl Last change: 8.5 3
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
to
call
when a
par-
ticu-
lar
limit
is
exceeded.
If the
handler-
Proc
removes
or
raises
the
limit
during
its
pro-
cess-
ing,
the
lim-
ited
inter-
preter
will
be
per-
mitted
to
con-
tinue
to
pro-
cess
after
the
handler
returns.
Many
handlers
may be
attached
to the
same
inter-
preter
limit;
their
order
Tcl Last change: 8.5 4
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
of
execu-
tion
is not
defined,
and
they
must
be
iden-
tified
by
handler-
Proc
and
client-
Data
when
they
are
deleted.
ClientData clientData (in) Arbitrary
pointer-
sized
word
used
to
pass
some
con-
text
to the
handler-
Proc
func-
tion.
Tcl_LimitHandlerDeleteProc *deleteProc (in) Function
to
call
when-
ever a
handler
is
deleted.
May be
NULL
if the
client-
Data
requires
Tcl Last change: 8.5 5
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
no
dele-
tion.
_________________________________________________________________
Tcl's interpreter resource limit subsystem allows for close
control over how much computation time a script may use, and
is useful for cases where a program is divided into multiple
pieces where some parts are more trusted than others (e.g.
web application servers).
Every interpreter may have a limit on the wall-time for exe-
cution, and a limit on the number of commands that the
interpreter may execute. Since checking of these limits is
potentially expensive (especially the time limit), each
limit also has a checking granularity, which is a divisor
for an internal count of the number of points in the core
where a check may be performed (which is immediately before
executing a command and at an unspecified frequency between
running commands, which can happen in empty-bodied while
loops).
The final component of the limit engine is a callback scheme
which allows for notifications of when a limit has been
exceeded. These callbacks can just provide logging, or may
allocate more resources to the interpreter to permit it to
continue processing longer.
When a limit is exceeded (and the callbacks have run; the
order of execution of the callbacks is unspecified) execu-
tion in the limited interpreter is stopped by raising an
error and setting a flag that prevents the catch command in
that interpreter from trapping that error. It is up to the
context that started execution in that interpreter (typi-
cally a master interpreter) to handle the error.
To check the resource limits for an interpreter, call
Tcl_LimitCheck, which returns TCL_OK if the limit was not
exceeded (after processing callbacks) and TCL_ERROR if the
limit was exceeded (in which case an error message is also
placed in the interpreter result). That function should
only be called when Tcl_LimitReady returns non-zero so that
granularity policy is enforced. This API is designed to be
similar in usage to Tcl_AsyncReady and Tcl_AsyncInvoke.
When writing code that may behave like catch in respect of
errors, you should only trap an error if Tcl_LimitExceeded
returns zero. If it returns non-zero, the interpreter is in
a limit-exceeded state and errors should be allowed to
Tcl Last change: 8.5 6
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
propagate to the calling context. You can also check
whether a particular type of limit has been exceeded using
Tcl_LimitTypeExceeded.
To check whether a limit has been set (but not whether it
has actually been exceeded) on an interpreter, call
Tcl_LimitTypeEnabled with the type of limit you want to
check. To enable a particular limit call Tcl_LimitTypeSet,
and to disable a limit call Tcl_LimitTypeReset.
The level of a command limit may be set using
Tcl_LimitSetCommands, and retrieved using
Tcl_LimitGetCommands. Similarly for a time limit with
Tcl_LimitSetTime and Tcl_LimitGetTime respectively, but with
that API the time limit is copied from and to the Tcl_Time
structure that the timeLimitPtr argument points to.
The checking granularity for a particular limit may be set
using Tcl_LimitSetGranularity and retrieved using
Tcl_LimitGetGranularity. Note that granularities must
always be positive.
LIMIT CALLBACKS
To add a handler callback to be invoked when a limit is
exceeded, call Tcl_LimitAddHandler. The handlerProc argu-
ment describes the function that will actually be called; it
should have the following prototype:
typedef void Tcl_LimitHandlerProc(
ClientData clientData,
Tcl_Interp *interp);
The clientData argument to the handler will be whatever is
passed to the clientData argument to Tcl_LimitAddHandler,
and the interp is the interpreter that had its limit
exceeded.
The deleteProc argument to Tcl_LimitAddHandler is a function
to call to delete the clientData value. It may be
TCL_STATIC or NULL if no deletion action is necessary, or
TCL_DYNAMIC if all that is necessary is to free the struc-
ture with Tcl_Free. Otherwise, it should refer to a func-
tion with the following prototype:
typedef void Tcl_LimitHandlerDeleteProc(
ClientData clientData);
A limit handler may be deleted using Tcl_LimitRemoveHandler;
the handler removed will be the first one found (out of the
handlers added with Tcl_LimitAddHandler) with exactly match-
ing type, handlerProc and clientData arguments. This
Tcl Last change: 8.5 7
Tcl_LimitCheck(3) Tcl Library Procedures Tcl_LimitCheck(3)
function always invokes the deleteProc on the clientData
(unless the deleteProc was NULL or TCL_STATIC).
interpreter, resource, limit, commands, time, callback
Tcl Last change: 8.5 8