summaryrefslogtreecommitdiffstats
path: root/doc/TraceCmd.3
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2014-10-09 14:56:27 (GMT)
committerdgp <dgp@users.sourceforge.net>2014-10-09 14:56:27 (GMT)
commit772c33dcd262689e9b046ab5985e5159fe415fb7 (patch)
treeb8cc50ac03a552b9278a52bc7d62f6db0734fef2 /doc/TraceCmd.3
parent6567599f3a6075b0a76cf29288488901aa6a6579 (diff)
parent941cd63bb1b0dbccbdf9827395beda4f1868406f (diff)
downloadtcl-772c33dcd262689e9b046ab5985e5159fe415fb7.zip
tcl-772c33dcd262689e9b046ab5985e5159fe415fb7.tar.gz
tcl-772c33dcd262689e9b046ab5985e5159fe415fb7.tar.bz2
[2039178] Remove false claims about TCL_INTERP_DESTROYED flag bit in command traces.
Diffstat (limited to 'doc/TraceCmd.3')
-rw-r--r--doc/TraceCmd.333
1 files changed, 10 insertions, 23 deletions
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 1244576..db2f5d5 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -86,11 +86,14 @@ operation is being performed on the command. 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).
+\fBTCL_TRACE_DESTROYED\fR below for more details). Because the
+deletion of commands can take place as part of the deletion of the interp
+that contains them, \fIproc\fR must be careful about checking what
+the passed in \fIinterp\fR value can be called upon 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. The function of \fIproc\fR
+in that circumstance is limited to the cleanup of its own data structures.
.PP
\fBTcl_UntraceCommand\fR may be used to remove a trace. If the
command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
@@ -123,7 +126,8 @@ traces for a given command that have the same \fIproc\fR.
.PP
During rename traces, the command being renamed is visible with both
names simultaneously, and the command still exists during delete
-traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no
+traces, unless the interp that contains it is being deleted.
+However, there is no
mechanism for signaling that an error occurred in a trace procedure,
so great care should be taken that errors do not get silently lost.
.SH "MULTIPLE TRACES"
@@ -142,22 +146,5 @@ rename the command, the last renaming takes precedence.
In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
is set in \fIflags\fR.
.\" Perhaps need some more comments here? - DKF
-.SH "TCL_INTERP_DESTROYED"
-.PP
-When an interpreter is destroyed, unset traces are called for
-all of its commands.
-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.
.SH KEYWORDS
clientData, trace, command