diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
commit | 5514e37335c012cc70f5b9aee3cedfe3d57f583f (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/Limit.3 | |
parent | 768f87f613cc9789fcf8073018fa02178c8c91df (diff) | |
download | blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.zip blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.gz blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.bz2 |
undo subtree
Diffstat (limited to 'tcl8.6/doc/Limit.3')
-rw-r--r-- | tcl8.6/doc/Limit.3 | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/tcl8.6/doc/Limit.3 b/tcl8.6/doc/Limit.3 deleted file mode 100644 index 20a2e02..0000000 --- a/tcl8.6/doc/Limit.3 +++ /dev/null @@ -1,192 +0,0 @@ -'\" -'\" Copyright (c) 2004 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH 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 -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_LimitCheck\fR(\fIinterp\fR) -.sp -int -\fBTcl_LimitReady\fR(\fIinterp\fR) -.sp -int -\fBTcl_LimitExceeded\fR(\fIinterp\fR) -.sp -int -\fBTcl_LimitTypeExceeded\fR(\fIinterp, type\fR) -.sp -int -\fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR) -.sp -void -\fBTcl_LimitTypeSet\fR(\fIinterp, type\fR) -.sp -void -\fBTcl_LimitTypeReset\fR(\fIinterp, type\fR) -.sp -int -\fBTcl_LimitGetCommands\fR(\fIinterp\fR) -.sp -void -\fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR) -.sp -void -\fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR) -.sp -void -\fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR) -.sp -int -\fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR) -.sp -void -\fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR) -.sp -void -\fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR) -.sp -void -\fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR) -.SH ARGUMENTS -.AS Tcl_LimitHandlerDeleteProc commandLimit in/out -.AP Tcl_Interp *interp in -Interpreter that the limit being managed applies to or that will have -its limits checked. -.AP int type in -The type of limit that the operation refers to. This must be either -\fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR. -.AP int commandLimit in -The maximum number of commands (as reported by \fBinfo cmdcount\fR) -that may be executed in the interpreter. -.AP Tcl_Time *timeLimitPtr in/out -A pointer to a structure that will either have the new time limit read -from (\fBTcl_LimitSetTime\fR) or the current time limit written to -(\fBTcl_LimitGetTime\fR). -.AP int granularity in -Divisor that indicates how often a particular limit should really be -checked. Must be at least 1. -.AP Tcl_LimitHandlerProc *handlerProc in -Function to call when a particular limit is exceeded. If the -\fIhandlerProc\fR removes or raises the limit during its processing, -the limited interpreter will be permitted to continue to process after -the handler returns. Many handlers may be attached to the same -interpreter limit; their order of execution is not defined, and they -must be identified by \fIhandlerProc\fR and \fIclientData\fR when they -are deleted. -.AP ClientData clientData in -Arbitrary pointer-sized word used to pass some context to the -\fIhandlerProc\fR function. -.AP Tcl_LimitHandlerDeleteProc *deleteProc in -Function to call whenever a handler is deleted. May be NULL if the -\fIclientData\fR requires no deletion. -.BE -.SH DESCRIPTION -.PP -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). -.PP -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 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 \fBwhile\fR loops). -.PP -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. -.PP -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 \fBcatch\fR 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. -.SH "LIMIT CHECKING API" -.PP -To check the resource limits for an interpreter, call -\fBTcl_LimitCheck\fR, which returns \fBTCL_OK\fR if the limit was not -exceeded (after processing callbacks) and \fBTCL_ERROR\fR 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 -\fBTcl_LimitReady\fR returns non-zero so that granularity policy is -enforced. This API is designed to be similar in usage to -\fBTcl_AsyncReady\fR and \fBTcl_AsyncInvoke\fR. -.PP -When writing code that may behave like \fBcatch\fR in respect of -errors, you should only trap an error if \fBTcl_LimitExceeded\fR -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 \fBTcl_LimitTypeExceeded\fR. -.SH "LIMIT CONFIGURATION" -.PP -To check whether a limit has been set (but not whether it has actually -been exceeded) on an interpreter, call \fBTcl_LimitTypeEnabled\fR with -the type of limit you want to check. To enable a particular limit -call \fBTcl_LimitTypeSet\fR, and to disable a limit call -\fBTcl_LimitTypeReset\fR. -.PP -The level of a command limit may be set using -\fBTcl_LimitSetCommands\fR, and retrieved using -\fBTcl_LimitGetCommands\fR. Similarly for a time limit with -\fBTcl_LimitSetTime\fR and \fBTcl_LimitGetTime\fR respectively, but -with that API the time limit is copied from and to the Tcl_Time -structure that the \fItimeLimitPtr\fR argument points to. -.PP -The checking granularity for a particular limit may be set using -\fBTcl_LimitSetGranularity\fR and retrieved using -\fBTcl_LimitGetGranularity\fR. Note that granularities must always be -positive. -.SS "LIMIT CALLBACKS" -.PP -To add a handler callback to be invoked when a limit is exceeded, call -\fBTcl_LimitAddHandler\fR. The \fIhandlerProc\fR argument describes -the function that will actually be called; it should have the -following prototype: -.PP -.CS -typedef void \fBTcl_LimitHandlerProc\fR( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -.PP -The \fIclientData\fR argument to the handler will be whatever is -passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR, -and the \fIinterp\fR is the interpreter that had its limit exceeded. -.PP -The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a -function to call to delete the \fIclientData\fR value. It may be -\fBTCL_STATIC\fR or NULL if no deletion action is necessary, or -\fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with -\fBTcl_Free\fR. Otherwise, it should refer to a function with the -following prototype: -.PP -.CS -typedef void \fBTcl_LimitHandlerDeleteProc\fR( - ClientData \fIclientData\fR); -.CE -.PP -A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the -handler removed will be the first one found (out of the handlers added -with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR, -\fIhandlerProc\fR and \fIclientData\fR arguments. This function -always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless -the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR). -.SH KEYWORDS -interpreter, resource, limit, commands, time, callback |