Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_LimitCheck(3)                          Tcl Library Procedures                          Tcl_LimitCheck(3)



____________________________________________________________________________________________________________

NAME
       Tcl_LimitAddHandler,  Tcl_LimitCheck,  Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_LimitGetGranular-ity, Tcl_LimitGetGranularity,
       ity, Tcl_LimitGetTime, Tcl_LimitReady,  Tcl_LimitRemoveHandler,  Tcl_LimitSetCommands,  Tcl_LimitSet-Granularity, Tcl_LimitSetGranularity,
       Granularity,   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_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 current time limit written to  (Tcl_Lim-itGetTime). (Tcl_LimitGetTime).
                                                             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 handlerProc removes or raises
                                                             the  limit  during  its processing, the limited
                                                             interpreter will be permitted  to  continue  to
                                                             process  after  the handler returns.  Many han-dlers handlers
                                                             dlers 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 dele-tion. deletion.
                                                             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  com-mands commands
       mands  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 immedi-ately immediately
       ately 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 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 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 con-text context
       text 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 par-ticular particular
       ticular 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  inter-preter, interpreter,
       preter,  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_LimitGet-Commands. Tcl_LimitGetCommands.
       Commands.   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 argu-ment argument
       ment 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 han-dlerProc handlerProc
       dlerProc  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 deletion action is necessary, or TCL_DYNAMIC if all that is neces-sary necessary
       sary  is to free the structure with Tcl_Free.  Otherwise, it should refer to a function with the fol-lowing following
       lowing 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, handler-Proc handlerProc
       Proc 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)