Tcl_LimitCheck(3)					      Tcl Library Procedures						 Tcl_LimitCheck(3)

__________________________________________________________________________________________________________________________________________________

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_COM-
							     MANDS 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_Lim-
							     itSetTime) 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 call-
       backs 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 func-
       tion 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 func-
       tion 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

Tcl									8.5							 Tcl_LimitCheck(3)