diff options
author | dgp <dgp@users.sourceforge.net> | 2019-05-11 14:43:06 (GMT) |
---|---|---|
committer | dgp <dgp@users.sourceforge.net> | 2019-05-11 14:43:06 (GMT) |
commit | 7278c6fb2c9bd8691b60e61ac24a57a85d10c1ae (patch) | |
tree | 08b764c9ce098219811a709ca8d0f5962744bf96 /doc | |
parent | 0c863ddec8f39d1afec9b67d4e899e4489d6f46e (diff) | |
parent | 923a6774f62e32298b5e46435e6a648e4ff1f53a (diff) | |
download | tcl-7278c6fb2c9bd8691b60e61ac24a57a85d10c1ae.zip tcl-7278c6fb2c9bd8691b60e61ac24a57a85d10c1ae.tar.gz tcl-7278c6fb2c9bd8691b60e61ac24a57a85d10c1ae.tar.bz2 |
Complete doc changes for TIP 543 in Tcl 8.7
Diffstat (limited to 'doc')
-rw-r--r-- | doc/TraceVar.3 | 39 |
1 files changed, 14 insertions, 25 deletions
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index e481985..82aa7b8 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -5,7 +5,7 @@ '\" 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 7.4 Tcl "Tcl Library Procedures" +.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -160,10 +160,6 @@ 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 @@ -330,12 +326,21 @@ 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 -is a partially formed result in the interpreter's result area. If +are partially formed results stored in the interpreter. If the trace procedure does anything that could damage this result (such -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. +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. .SH "UNDEFINED VARIABLES" .PP It is legal to set a trace on an undefined variable. @@ -354,24 +359,8 @@ 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 "TCL_INTERP_DESTROYED" -.PP -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" |