DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_LimitAddHandler(3tcl)




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)

Tcl                     Last change: 8.5                        1

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

     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
                                                           either
                                                           TCL_LIMIT_COMMANDS
                                                           or
                                                           TCL_LIMIT_TIME.

     int commandLimit (in)                                 The
                                                           max-
                                                           imum
                                                           number
                                                           of
                                                           com-
                                                           mands
                                                           (as
                                                           reported
                                                           by
                                                           info
                                                           cmdcount)

Tcl                     Last change: 8.5                        2

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

                                                           that
                                                           may be
                                                           exe-
                                                           cuted
                                                           in the
                                                           inter-
                                                           preter.

     Tcl_Time *timeLimitPtr (in/out)                       A
                                                           pointer
                                                           to   a
                                                           struc-
                                                           ture
                                                           that
                                                           will
                                                           either
                                                           have
                                                           the
                                                           new
                                                           time
                                                           limit
                                                           read
                                                           from
                                                           (Tcl_LimitSetTime)
                                                           or the
                                                           current
                                                           time
                                                           limit
                                                           writ-
                                                           ten to
                                                           (Tcl_LimitGetTime).

     int granularity (in)                                  Divisor
                                                           that
                                                           indi-
                                                           cates
                                                           how
                                                           often
                                                           a par-
                                                           ticu-
                                                           lar
                                                           limit
                                                           should
                                                           really
                                                           be
                                                           checked.
                                                           Must
                                                           be  at
                                                           least
                                                           1.

     Tcl_LimitHandlerProc *handlerProc (in)                Function

Tcl                     Last change: 8.5                        3

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

                                                           to
                                                           call
                                                           when a
                                                           par-
                                                           ticu-
                                                           lar
                                                           limit
                                                           is
                                                           exceeded.
                                                           If the
                                                           handler-
                                                           Proc
                                                           removes
                                                           or
                                                           raises
                                                           the
                                                           limit
                                                           during
                                                           its
                                                           pro-
                                                           cess-
                                                           ing,
                                                           the
                                                           lim-
                                                           ited
                                                           inter-
                                                           preter
                                                           will
                                                           be
                                                           per-
                                                           mitted
                                                           to
                                                           con-
                                                           tinue
                                                           to
                                                           pro-
                                                           cess
                                                           after
                                                           the
                                                           handler
                                                           returns.
                                                           Many
                                                           handlers
                                                           may be
                                                           attached
                                                           to the
                                                           same
                                                           inter-
                                                           preter
                                                           limit;
                                                           their
                                                           order

Tcl                     Last change: 8.5                        4

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

                                                           of
                                                           execu-
                                                           tion
                                                           is not
                                                           defined,
                                                           and
                                                           they
                                                           must
                                                           be
                                                           iden-
                                                           tified
                                                           by
                                                           handler-
                                                           Proc
                                                           and
                                                           client-
                                                           Data
                                                           when
                                                           they
                                                           are
                                                           deleted.

     ClientData clientData (in)                            Arbitrary
                                                           pointer-
                                                           sized
                                                           word
                                                           used
                                                           to
                                                           pass
                                                           some
                                                           con-
                                                           text
                                                           to the
                                                           handler-
                                                           Proc
                                                           func-
                                                           tion.

     Tcl_LimitHandlerDeleteProc *deleteProc (in)           Function
                                                           to
                                                           call
                                                           when-
                                                           ever a
                                                           handler
                                                           is
                                                           deleted.
                                                           May be
                                                           NULL
                                                           if the
                                                           client-
                                                           Data
                                                           requires

Tcl                     Last change: 8.5                        5

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

                                                           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 exe-
     cution,  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 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) execu-
     tion 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 (typi-
     cally 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

Tcl                     Last change: 8.5                        6

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

     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 argu-
     ment 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 necessary is to free the struc-
     ture with Tcl_Free.  Otherwise, it should refer to  a  func-
     tion 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 match-
     ing   type,  handlerProc  and  clientData  arguments.   This

Tcl                     Last change: 8.5                        7

Tcl_LimitCheck(3)    Tcl Library Procedures     Tcl_LimitCheck(3)

     function always invokes the  deleteProc  on  the  clientData
     (unless the deleteProc was NULL or TCL_STATIC).


KEYWORDS

     interpreter, resource, limit, commands, time, callback

Tcl                     Last change: 8.5                        8


Man(1) output converted with man2html