'\"
'\" Copyright (c) 2004 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Limit.3,v 1.7 2004/11/12 09:01:25 das Exp $
'\" 
.so man.macros
.TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH 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
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_LimitCheck\fR(\fIinterp\fR)
.sp
int
\fBTcl_LimitReady\fR(\fIinterp\fR)
.sp
int
\fBTcl_LimitExceeded\fR(\fIinterp\fR)
.sp
int
\fBTcl_LimitTypeExceeded\fR(\fIinterp, type\fR)
.sp
int
\fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR)
.sp
void
\fBTcl_LimitTypeSet\fR(\fIinterp, type\fR)
.sp
void
\fBTcl_LimitTypeReset\fR(\fIinterp, type\fR)
.sp
int
\fBTcl_LimitGetCommands\fR(\fIinterp\fR)
.sp
void
\fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR)
.sp
void
\fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR)
.sp
void
\fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR)
.sp
int
\fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR)
.sp
void
\fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR)
.sp
void
\fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR)
.sp
void
\fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_LimitHandlerDeleteProc commandLimit in/out
.AP Tcl_Interp *interp in
Interpreter that the limit being managed applies to or that will have
its limits checked.
.AP int type in
The type of limit that the operation refers to.  This must be either
\fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
.AP int commandLimit in
The maximum number of commands (as reported by \fBinfo cmdcount\fR)
that may be executed in the interpreter.
.AP Tcl_Time *timeLimitPtr in/out
A pointer to a structure that will either have the new time limit read
from (\fBTcl_LimitSetTime\fR) or the current time limit written to
(\fBTcl_LimitGetTime\fR).
.AP int granularity in
Divisor that indicates how often a particular limit should really be
checked.  Must be at least 1.
.AP Tcl_LimitHandlerProc *handlerProc in
Function to call when a particular limit is exceeded.  If the
\fIhandlerProc\fR 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 \fIhandlerProc\fR and \fIclientData\fR when they
are deleted.
.AP ClientData clientData in
Arbitrary pointer-sized word used to pass some context to the
\fIhandlerProc\fR function.
.AP Tcl_LimitHandlerDeleteProc *deleteProc in
Function to call whenever a handler is deleted.  May be NULL if the
\fIclientData\fR requires no deletion.
.BE

.SH DESCRIPTION
.PP
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).
.PP
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 \fBwhile\fR loops).
.PP
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.
.PP
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 \fBcatch\fR 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.
.SH "LIMIT CHECKING API"
.PP
To check the resource limits for an interpreter, call
\fBTcl_LimitCheck\fR, which returns \fBTCL_OK\fR if the limit was not
exceeded (after processing callbacks) and \fBTCL_ERROR\fR 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
\fBTcl_LimitReady\fR returns non-zero so that granularity policy is
enforced.  This API is designed to be similar in usage to
\fBTcl_AsyncReady\fR and \fBTcl_AsyncInvoke\fR.
.PP
When writing code that may behave like \fBcatch\fR in respect of
errors, you should only trap an error if \fBTcl_LimitExceeded\fR
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 \fBTcl_LimitTypeExceeded\fR.
.SH "LIMIT CONFIGURATION"
.PP
To check whether a limit has been set (but not whether it has actually
been exceeded) on an interpreter, call \fBTcl_LimitTypeEnabled\fR with
the type of limit you want to check.  To enable a particular limit
call \fBTcl_LimitTypeSet\fR, and to disable a limit call
\fBTcl_LimitTypeReset\fR.
.PP
The level of a command limit may be set using
\fBTcl_LimitSetCommands\fR, and retrieved using
\fBTcl_LimitGetCommands\fR.  Similarly for a time limit with
\fBTcl_LimitSetTime\fR and \fBTcl_LimitGetTime\fR respectively, but
with that API the time limit is copied from and to the Tcl_Time
structure that the \fItimeLimitPtr\fR argument points to.
.PP
The checking granularity for a particular limit may be set using
\fBTcl_LimitSetGranularity\fR and retrieved using
\fBTcl_LimitGetGranularity\fR.  Note that granularities must always be
positive.
.SS "LIMIT CALLBACKS"
.PP
To add a handler callback to be invoked when a limit is exceeded, call
\fBTcl_LimitAddHandler\fR.  The \fIhandlerProc\fR argument describes
the function that will actually be called; it should have the
following prototype:
.PP
.CS
typedef void Tcl_LimitHandlerProc(
        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
.CE
.PP
The \fIclientData\fR argument to the handler will be whatever is
passed to the \fIclientData\fR argment to \fBTcl_LimitAddHandler\fR,
and the \fIinterp\fR is the interpreter that had its limit exceeded.
.PP
The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
function to call to delete the \fIclientData\fR value.  It may be
\fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
\fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
\fBTcl_Free\fR.  Otherwise, it should refer to a function with the
following prototype:
.PP
.CS
typedef void Tcl_LimitHandlerDeleteProc(
        ClientData \fIclientData\fR);
.CE
.PP
A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
handler removed will be the first one found (out of the handlers added
with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
\fIhandlerProc\fR and \fIclientData\fR arguments.  This function
always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).

.SH KEYWORDS
interpreter, resource, limit, commands, time, callback