util/X86LINUX64/man/man3/Tcl_LimitReady.3

   1 '\"
   2 '\" Copyright (c) 2004 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 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
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tcl.h>\fR
 281 .sp
 282 int
 283 \fBTcl_LimitCheck\fR(\fIinterp\fR)
 284 .sp
 285 int
 286 \fBTcl_LimitReady\fR(\fIinterp\fR)
 287 .sp
 288 int
 289 \fBTcl_LimitExceeded\fR(\fIinterp\fR)
 290 .sp
 291 int
 292 \fBTcl_LimitTypeExceeded\fR(\fIinterp, type\fR)
 293 .sp
 294 int
 295 \fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR)
 296 .sp
 297 void
 298 \fBTcl_LimitTypeSet\fR(\fIinterp, type\fR)
 299 .sp
 300 void
 301 \fBTcl_LimitTypeReset\fR(\fIinterp, type\fR)
 302 .sp
 303 int
 304 \fBTcl_LimitGetCommands\fR(\fIinterp\fR)
 305 .sp
 306 void
 307 \fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR)
 308 .sp
 309 void
 310 \fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR)
 311 .sp
 312 void
 313 \fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR)
 314 .sp
 315 int
 316 \fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR)
 317 .sp
 318 void
 319 \fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR)
 320 .sp
 321 void
 322 \fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR)
 323 .sp
 324 void
 325 \fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR)
 326 .SH ARGUMENTS
 327 .AS Tcl_LimitHandlerDeleteProc commandLimit in/out
 328 .AP Tcl_Interp *interp in
 329 Interpreter that the limit being managed applies to or that will have
 330 its limits checked.
 331 .AP int type in
 332 The type of limit that the operation refers to.  This must be either
 333 \fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
 334 .AP int commandLimit in
 335 The maximum number of commands (as reported by \fBinfo cmdcount\fR)
 336 that may be executed in the interpreter.
 337 .AP Tcl_Time *timeLimitPtr in/out
 338 A pointer to a structure that will either have the new time limit read
 339 from (\fBTcl_LimitSetTime\fR) or the current time limit written to
 340 (\fBTcl_LimitGetTime\fR).
 341 .AP int granularity in
 342 Divisor that indicates how often a particular limit should really be
 343 checked.  Must be at least 1.
 344 .AP Tcl_LimitHandlerProc *handlerProc in
 345 Function to call when a particular limit is exceeded.  If the
 346 \fIhandlerProc\fR removes or raises the limit during its processing,
 347 the limited interpreter will be permitted to continue to process after
 348 the handler returns.  Many handlers may be attached to the same
 349 interpreter limit; their order of execution is not defined, and they
 350 must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
 351 are deleted.
 352 .AP ClientData clientData in
 353 Arbitrary pointer-sized word used to pass some context to the
 354 \fIhandlerProc\fR function.
 355 .AP Tcl_LimitHandlerDeleteProc *deleteProc in
 356 Function to call whenever a handler is deleted.  May be NULL if the
 357 \fIclientData\fR requires no deletion.
 358 .BE
 359 .SH DESCRIPTION
 360 .PP
 361 Tcl's interpreter resource limit subsystem allows for close control
 362 over how much computation time a script may use, and is useful for
 363 cases where a program is divided into multiple pieces where some parts
 364 are more trusted than others (e.g. web application servers).
 365 .PP
 366 Every interpreter may have a limit on the wall-time for execution, and
 367 a limit on the number of commands that the interpreter may execute.
 368 Since checking of these limits is potentially expensive (especially
 369 the time limit), each limit also has a checking granularity, which is
 370 a divisor for an internal count of the number of points in the core
 371 where a check may be performed (which is immediately before executing
 372 a command and at an unspecified frequency between running commands,
 373 which can happen in empty-bodied \fBwhile\fR loops).
 374 .PP
 375 The final component of the limit engine is a callback scheme which
 376 allows for notifications of when a limit has been exceeded.  These
 377 callbacks can just provide logging, or may allocate more resources to
 378 the interpreter to permit it to continue processing longer.
 379 .PP
 380 When a limit is exceeded (and the callbacks have run; the order of
 381 execution of the callbacks is unspecified) execution in the limited
 382 interpreter is stopped by raising an error and setting a flag that
 383 prevents the \fBcatch\fR command in that interpreter from trapping
 384 that error.  It is up to the context that started execution in that
 385 interpreter (typically a master interpreter) to handle the error.
 386 .SH "LIMIT CHECKING API"
 387 .PP
 388 To check the resource limits for an interpreter, call
 389 \fBTcl_LimitCheck\fR, which returns \fBTCL_OK\fR if the limit was not
 390 exceeded (after processing callbacks) and \fBTCL_ERROR\fR if the limit was
 391 exceeded (in which case an error message is also placed in the
 392 interpreter result).  That function should only be called when
 393 \fBTcl_LimitReady\fR returns non-zero so that granularity policy is
 394 enforced.  This API is designed to be similar in usage to
 395 \fBTcl_AsyncReady\fR and \fBTcl_AsyncInvoke\fR.
 396 .PP
 397 When writing code that may behave like \fBcatch\fR in respect of
 398 errors, you should only trap an error if \fBTcl_LimitExceeded\fR
 399 returns zero.  If it returns non-zero, the interpreter is in a
 400 limit-exceeded state and errors should be allowed to propagate to the
 401 calling context.  You can also check whether a particular type of
 402 limit has been exceeded using \fBTcl_LimitTypeExceeded\fR.
 403 .SH "LIMIT CONFIGURATION"
 404 .PP
 405 To check whether a limit has been set (but not whether it has actually
 406 been exceeded) on an interpreter, call \fBTcl_LimitTypeEnabled\fR with
 407 the type of limit you want to check.  To enable a particular limit
 408 call \fBTcl_LimitTypeSet\fR, and to disable a limit call
 409 \fBTcl_LimitTypeReset\fR.
 410 .PP
 411 The level of a command limit may be set using
 412 \fBTcl_LimitSetCommands\fR, and retrieved using
 413 \fBTcl_LimitGetCommands\fR.  Similarly for a time limit with
 414 \fBTcl_LimitSetTime\fR and \fBTcl_LimitGetTime\fR respectively, but
 415 with that API the time limit is copied from and to the Tcl_Time
 416 structure that the \fItimeLimitPtr\fR argument points to.
 417 .PP
 418 The checking granularity for a particular limit may be set using
 419 \fBTcl_LimitSetGranularity\fR and retrieved using
 420 \fBTcl_LimitGetGranularity\fR.  Note that granularities must always be
 421 positive.
 422 .SS "LIMIT CALLBACKS"
 423 .PP
 424 To add a handler callback to be invoked when a limit is exceeded, call
 425 \fBTcl_LimitAddHandler\fR.  The \fIhandlerProc\fR argument describes
 426 the function that will actually be called; it should have the
 427 following prototype:
 428 .PP
 429 .CS
 430 typedef void \fBTcl_LimitHandlerProc\fR(
 431         ClientData \fIclientData\fR,
 432         Tcl_Interp *\fIinterp\fR);
 433 .CE
 434 .PP
 435 The \fIclientData\fR argument to the handler will be whatever is
 436 passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR,
 437 and the \fIinterp\fR is the interpreter that had its limit exceeded.
 438 .PP
 439 The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
 440 function to call to delete the \fIclientData\fR value.  It may be
 441 \fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
 442 \fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
 443 \fBTcl_Free\fR.  Otherwise, it should refer to a function with the
 444 following prototype:
 445 .PP
 446 .CS
 447 typedef void \fBTcl_LimitHandlerDeleteProc\fR(
 448         ClientData \fIclientData\fR);
 449 .CE
 450 .PP
 451 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
 452 handler removed will be the first one found (out of the handlers added
 453 with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
 454 \fIhandlerProc\fR and \fIclientData\fR arguments.  This function
 455 always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
 456 the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).
 457 .SH KEYWORDS
 458 interpreter, resource, limit, commands, time, callback