Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_LimitCheck(3)	    Tcl	Library	Procedures	     Tcl_LimitCheck(3)

______________________________________________________________________________

NAME
       Tcl_LimitAddHandler,  Tcl_LimitCheck,  Tcl_LimitExceeded, Tcl_LimitGet-
       Commands,  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)

       Tcl_LimitTypeSet(interp,	type)

       Tcl_LimitTypeReset(interp, type)

       int
       Tcl_LimitGetCommands(interp)

       Tcl_LimitSetCommands(interp, commandLimit)

       Tcl_LimitGetTime(interp,	timeLimitPtr)

       Tcl_LimitSetTime(interp,	timeLimitPtr)

       int
       Tcl_LimitGetGranularity(interp, type)

       Tcl_LimitSetGranularity(interp, type, granularity)

       Tcl_LimitAddHandler(interp, type, handlerProc, clientData, deleteProc)

       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	opera-
							     tion  refers  to.
							     This must be  ei-
							     ther
							     TCL_LIMIT_COM-
							     MANDS	    or
							     TCL_LIMIT_TIME.

       Tcl_Size	commandLimit (in)			     The maximum  num-
							     ber  of  commands
							     (as  reported  by
							     info    cmdcount)
							     that may be  exe-
							     cuted  in the in-
							     terpreter.

       Tcl_Time	*timeLimitPtr (in/out)			     A	pointer	 to  a
							     structure	  that
							     will either  have
							     the    new	  time
							     limit  read  from
							     (Tcl_LimitSet-
							     Time) or the cur-
							     rent  time	 limit
							     written	    to
							     (Tcl_LimitGet-
							     Time).

       int granularity (in)				     Divisor  that in-
							     dicates how often
							     a	    particular
							     limit  should re-
							     ally be  checked.
							     Must  be at least
							     1.

       Tcl_LimitHandlerProc *handlerProc (in)		     Function to  call
							     when a particular
							     limit    is   ex-
							     ceeded.   If  the
							     handlerProc   re-
							     moves  or	raises
							     the  limit	during
							     its   processing,
							     the  limited  in-
							     terpreter will be
							     permitted to con-
							     tinue to  process
							     after the handler
							     returns.	  Many
							     handlers  may  be
							     attached  to  the
							     same  interpreter
							     limit;  their or-
							     der of  execution
							     is	 not  defined,
							     and they must  be
							     identified	    by
							     handlerProc   and
							     clientData	  when
							     they are deleted.

       void *clientData	(in)				     Arbitrary
							     pointer-sized
							     word used to pass
							     some  context  to
							     the   handlerProc
							     function.

       Tcl_LimitHandlerDeleteProc *deleteProc (in)	     Function to  call
							     whenever  a  han-
							     dler is  deleted.
							     May  be  NULL  if
							     the    clientData
							     requires no dele-
							     tion.
______________________________________________________________________________

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 di-
       visor 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 al-
       lows 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 exe-
       cution of the callbacks is unspecified) execution in the	limited	inter-
       preter 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
       the main	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 re-
       turns 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(
		      void *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	 dele-
       tion 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(
		      void *clientData);

       A limit handler may be deleted using Tcl_LimitRemoveHandler;  the  han-
       dler  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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_LimitSetCommands.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help