diff options
Diffstat (limited to 'doc/TraceVar.3')
| -rw-r--r-- | doc/TraceVar.3 | 63 |
1 files changed, 31 insertions, 32 deletions
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 5de6a44..97af6d4 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -4,8 +4,8 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures" +'\" +.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -95,7 +95,7 @@ Invoke \fIproc\fR whenever an attempt is made to modify the variable. Invoke \fIproc\fR whenever the variable is unset. A variable may be unset either explicitly by an \fBunset\fR command, or implicitly when a procedure returns (its local variables are -automatically unset) or when the interpreter or namespace is deleted (all +automatically unset) or when the interpreter is deleted (all variables are automatically unset). .TP \fBTCL_TRACE_ARRAY\fR @@ -121,16 +121,14 @@ Whenever one of the specified operations occurs on the variable, \fIproc\fR will be invoked. It should have arguments and result that match the type \fBTcl_VarTraceProc\fR: -.PP .CS -typedef char *\fBTcl_VarTraceProc\fR( +typedef char *Tcl_VarTraceProc( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, - const char *\fIname1\fR, - const char *\fIname2\fR, + char *\fIname1\fR, + char *\fIname2\fR, int \fIflags\fR); .CE -.PP The \fIclientData\fR and \fIinterp\fR parameters will have the same values as those passed to \fBTcl_TraceVar\fR when the trace was created. @@ -160,6 +158,10 @@ The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about to be destroyed; this information may be useful to \fIproc\fR so that it can clean up its own internal data structures (see the section \fBTCL_TRACE_DESTROYED\fR below for more details). +Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire +interpreter is being destroyed. +When this bit is set, \fIproc\fR must be especially careful in +the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below). The trace procedure's return value should normally be NULL; see \fBERROR RETURNS\fR below for information on other possibilities. .PP @@ -199,7 +201,7 @@ The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and except that the name of the variable consists of two parts. \fIName1\fR gives the name of a scalar variable or array, and \fIname2\fR gives the name of an element within an array. -When \fIname2\fR is NULL, +When \fIname2\fR is NULL, \fIname1\fR may contain both an array and an element name: if the name contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is @@ -210,7 +212,7 @@ If \fIname2\fR is NULL and \fIname1\fR does not refer to an array element it means that either the variable is a scalar or the trace is to be set on the entire array rather than an individual element (see WHOLE-ARRAY TRACES below for -more information). +more information). .SH "ACCESSING VARIABLES DURING TRACES" .PP During read, write, and array traces, the @@ -326,21 +328,12 @@ During unset traces, the return value is ignored and all relevant trace procedures will always be invoked. .SH "RESTRICTIONS" .PP -Because operations on variables may take place as part of the deletion -of the interp that contains them, \fIproc\fR must be careful about checking -what the \fIinterp\fR parameter can be used to do. -The routine \fBTcl_InterpDeleted\fR is an important tool for this. -When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able -to invoke any scripts in \fIinterp\fR. You may encounter old code using -a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this -condition, but any supported code should be converted to stop using it. -.PP A trace procedure can be called at any time, even when there -are partially formed results stored in the interpreter. If +is a partially formed result in the interpreter's result area. If the trace procedure does anything that could damage this result (such -as calling \fBTcl_Eval\fR) then it must use the \fBTcl_SaveInterpState\fR -and related routines to save and restore the original state of -the interpreter before it returns. +as calling \fBTcl_Eval\fR) then it must save the original values of +the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore +them before it returns. .SH "UNDEFINED VARIABLES" .PP It is legal to set a trace on an undefined variable. @@ -359,19 +352,25 @@ Traces on a variable are always removed whenever the variable is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not set is for a whole-array trace invoked when only a single element of an array is unset. -.SH "REFERENCE COUNT MANAGEMENT" +.SH "TCL_INTERP_DESTROYED" .PP -When a \fIproc\fR callback is invoked, and that callback was installed with -the \fBTCL_TRACE_RESULT_OBJECT\fR flag, the result of the callback is a -Tcl_Obj reference when there is an error. The result will have its reference -count decremented once when no longer needed, or may have additional -references made to it (e.g., by setting it as the interpreter result with -\fBTcl_SetObjResult\fR). +When an interpreter is destroyed, unset traces are called for +all of its variables. +The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR +argument passed to the trace procedures. +Trace procedures must be extremely careful in what they do if +the \fBTCL_INTERP_DESTROYED\fR bit is set. +It is not safe for the procedures to invoke any Tcl procedures +on the interpreter, since its state is partially deleted. +All that trace procedures should do under these circumstances is +to clean up and free their own internal data structures. .SH BUGS .PP +Tcl does not do any error checking to prevent trace procedures +from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR +set. +.PP Array traces are not yet integrated with the Tcl \fBinfo exists\fR command, nor is there Tcl-level access to array traces. -.SH "SEE ALSO" -trace(n) .SH KEYWORDS clientData, trace, variable |