NAME¶
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
SYNOPSIS¶
#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)
void
Tcl_LimitAddHandler(interp, type, handlerProc, clientData, deleteProc)
void
Tcl_LimitRemoveHandler(interp, type, handlerProc, clientData)
ARGUMENTS¶
- 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 operation refers to. This must be either
TCL_LIMIT_COMMANDS or TCL_LIMIT_TIME.
- int commandLimit (in)
- The maximum number of commands (as reported by info cmdcount) that
may be executed in the interpreter.
- Tcl_Time *timeLimitPtr (in/out)
- A pointer to a structure that will either have the new time limit read
from ( Tcl_LimitSetTime) or the current time limit written to (
Tcl_LimitGetTime).
- int granularity (in)
- Divisor that indicates how often a particular limit should really be
checked. Must be at least 1.
- Tcl_LimitHandlerProc *handlerProc (in)
- Function to call when a particular limit is exceeded. If the
handlerProc removes or raises the limit during its processing, the
limited interpreter will be permitted to continue to process after the
handler returns. Many handlers may be attached to the same interpreter
limit; their order of execution is not defined, and they must be
identified by handlerProc and clientData when they are
deleted.
- ClientData clientData (in)
- Arbitrary pointer-sized word used to pass some context to the
handlerProc function.
- Tcl_LimitHandlerDeleteProc *deleteProc (in)
- Function to call whenever a handler is deleted. May be NULL if the
clientData requires no deletion.
DESCRIPTION¶
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 execution, 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) execution 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 (typically a master interpreter) to
handle the error.
LIMIT CHECKING API¶
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 propagate to the calling context. You can also check
whether a particular type of limit has been exceeded using
Tcl_LimitTypeExceeded.
LIMIT CONFIGURATION¶
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 argument 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 structure with
Tcl_Free. Otherwise, it should
refer to a function 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 matching
type,
handlerProc and
clientData arguments. This function always
invokes the
deleteProc on the
clientData (unless the
deleteProc was NULL or
TCL_STATIC).
KEYWORDS¶
interpreter, resource, limit, commands, time, callback