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)

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

       int 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.

       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  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
       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 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(
		      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	 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(
		      ClientData 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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | LIMIT CHECKING API | LIMIT CONFIGURATION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_LimitAddHandler.tcl86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help