From d416b6e8323e9eb7acce473eb5491cae6cf44447 Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 23 Apr 2002 13:09:50 +0000 Subject: Added documentation for command tracing API [Bug 414927] --- ChangeLog | 5 ++ doc/TraceCmd.3 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+) create mode 100644 doc/TraceCmd.3 diff --git a/ChangeLog b/ChangeLog index 4bd1566..fc63942 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2002-04-23 Donal K. Fellows + + * doc/TraceCmd.3: New file that documents Tcl_CommandTraceInfo, + Tcl_TraceCommand and Tcl_UntraceCommand [Bug 414927] + 2002-04-22 Jeff Hobbs * generic/tclIOUtil.c (Tcl_FSRegister, Tcl_FSUnregister): diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 new file mode 100644 index 0000000..f39d458 --- /dev/null +++ b/doc/TraceCmd.3 @@ -0,0 +1,170 @@ +'\" +'\" Copyright (c) 2002 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" CVS: @(#) $Id: TraceCmd.3,v 1.1 2002/04/23 13:09:51 dkf Exp $ +'\" +.so man.macros +.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +ClientData +\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR +.sp +int +\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +.sp +void +\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +.SH ARGUMENTS +.AS Tcl_CommandTraceProc prevClientData +.AP Tcl_Interp *interp in +Interpreter containing the command. +.AP "CONST char" *cmdName in +Name of command. +.AP int flags in +OR-ed collection of the value TCL_TRACE_RENAME and TCL_TRACE_DELETE. +.AP Tcl_CommandTraceProc *proc in +Procedure to call when specified operations occur to \fIcmdName\fR. +.AP ClientData clientData in +Arbitrary argument to pass to \fIproc\fR. +.AP ClientData prevClientData in +If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, +so this call will return information about next trace. If NULL, this +call will return information about first trace. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_TraceCommand\fR allows a C procedure to monitor operations +performed on a Tcl command, so that the C procedure is invoked +whenever the command is renamed or deleted. If the trace is created +successfully then \fBTcl_TraceCommand\fR returns TCL_OK. If an error +occurred (e.g. \fIcmdName\fR specifies a non-existent command) then +TCL_ERROR is returned and an error message is left in the +interpreter's result. +.PP +The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the +trace procedure is to be invoked. It consists of an OR-ed combination +of any of the following values: +.TP +\fBTCL_TRACE_RENAME\fR +Invoke \fIproc\fR whenever the command is renamed. +.TP +\fBTCL_TRACE_DELETE\fR +Invoke \fIproc\fR when the command is deleted. +.PP +Whenever one of the specified operations occurs to the command, +\fIproc\fR will be invoked. It should have arguments and result that +match the type \fBTcl_CommandTraceProc\fR: +.CS +typedef void Tcl_CommandTraceProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + CONST char *\fIoldName\fR, + CONST char *\fInewName\fR, + int \fIflags\fR); +.CE +The \fIclientData\fR and \fIinterp\fR parameters will have the same +values as those passed to \fBTcl_TraceCommand\fR when the trace was +created. \fIClientData\fR typically points to an application-specific +data structure that describes what to do when \fIproc\fR is invoked. +\fIOldName\fR gives the name of the command being renamed, and +\fInewName\fR gives the name that the command is being renamed to (or +an empty string or NULL when the command is being deleted.) +\fIFlags\fR is an OR-ed combination of bits potentially providing +several pieces of information. One of the bits TCL_TRACE_RENAME and +TCL_TRACE_DELETE will be set in \fIflags\fR to indicate which +operation is being performed on the command. The bit +TCL_TRACE_DESTROYED 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 +TCL_TRACE_DESTROYED below for more details). Lastly, the bit +TCL_INTERP_DESTROYED 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 TCL_INTERP_DESTROYED +below). +.PP +\fBTcl_UntraceCommand\fR may be used to remove a trace. If the +command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has +a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then +the corresponding trace is removed. If no such trace exists, then the +call to \fBTcl_UntraceCommand\fR has no effect. The same bits are +valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR. +.PP +\fBTcl_CommandTraceInfo\fR may be used to retrieve information about +traces set on a given command. +The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR +associated with a particular trace. +The trace must be on the command specified by the \fIinterp\fR, +\fIcmdName\fR, and \fIflags\fR arguments (note that currently the +flags are ignored; \fIflags\fR should be set to 0 for future +compatability) and its trace procedure must the same as the \fIproc\fR +argument. +If the \fIprevClientData\fR argument is NULL then the return +value corresponds to the first (most recently created) matching +trace, or NULL if there are no matching traces. +If the \fIprevClientData\fR argument isn't NULL, then it should +be the return value from a previous call to \fBTcl_CommandTraceInfo\fR. +In this case, the new return value will correspond to the next +matching trace after the one whose \fIclientData\fR matches +\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR +or if there are no more matching traces after it. +This mechanism makes it possible to step through all of the +traces for a given command that have the same \fIproc\fR. + +.SH "CALLING COMMANDS DURING TRACES" +.PP +During rename traces, the command being renamed is visible with both +names simultaneously, and the command still exists during delete +traces (if TCL_INTERP_DESTROYED is not set). However, there is no +mechanism for signalling that an error occurred in a trace procedure, +so great care should be taken that errors do not get silently lost. + +.SH "MULTIPLE TRACES" +.PP +It is possible for multiple traces to exist on the same command. +When this happens, all of the trace procedures will be invoked on each +access, in order from most-recently-created to least-recently-created. +Attempts to delete the command during a delete trace will fail +silently, since the command is already scheduled for deletion anyway. +If the command being renamed is renamed by one of its rename traces, +that renaming takes precedence over the one that triggered the trace +and the collection of traces will not be reexecuted; if several traces +rename the command, the last renaming takes precedence. + +..SH "TCL_TRACE_DESTROYED FLAG" +.PP +In a delete callback to \fIproc\fR, the TCL_TRACE_DESTROYED 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 TCL_INTERP_DESTROYED 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 TCL_INTERP_DESTROYED 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 doesn't do any error checking to prevent trace procedures +from misusing the interpreter during traces with TCL_INTERP_DESTROYED +set. + +.SH KEYWORDS +clientData, trace, command -- cgit v0.12