Unix/Linux Go Back    


CentOS 7.0 - man page for tcl_limitsetcommands (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tcl_LimitCheck(3)		      Tcl Library Procedures			Tcl_LimitCheck(3)

_________________________________________________________________________________________________

NAME
       Tcl_LimitAddHandler,  Tcl_LimitCheck,  Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_Limit-
       GetGranularity, Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler, Tcl_LimitSetCom-
       mands,  Tcl_LimitSetGranularity,  Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeEx-
       ceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet - manage and check resource limits on  inter-
       preters

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  cur-
							     rent time limit written to (Tcl_Lim-
							     itGetTime).

       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 handler-
							     Proc removes  or  raises  the  limit
							     during  its  processing, the limited
							     interpreter  will	be  permitted  to
							     continue  to  process after the han-
							     dler returns.  Many handlers may  be
							     attached  to  the	same  interpreter
							     limit; their order of  execution  is
							     not  defined, and they must be iden-
							     tified 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 computa-
       tion time a script may use, and is useful for cases where a program is divided into multi-
       ple 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 num-
       ber 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 granu-
       larity, 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 notifica-
       tions 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 call-
       backs 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_Limit-
       TypeExceeded.

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_Limit-
       TypeReset.

       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_LimitGet-
       Time  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 posi-
       tive.

   LIMIT CALLBACKS
       To add a handler callback to be invoked when a limit is	exceeded,  call  Tcl_LimitAddHan-
       dler.   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  argu-
       ment  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 client-
       Data  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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:55 AM.