507 lines
15 KiB
Plaintext
507 lines
15 KiB
Plaintext
'\"
|
|
'\" Generated from file '' by tcllib/doctools with format 'nroff'
|
|
'\"
|
|
.TH "ttrace" n 2\&.8 "Tcl Threading"
|
|
.\" The -*- nroff -*- definitions below are for supplemental macros used
|
|
.\" in Tcl/Tk manual entries.
|
|
.\"
|
|
.\" .AP type name in/out ?indent?
|
|
.\" Start paragraph describing an argument to a library procedure.
|
|
.\" type is type of argument (int, etc.), in/out is either "in", "out",
|
|
.\" or "in/out" to describe whether procedure reads or modifies arg,
|
|
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
|
|
.\" needed; use .AS below instead)
|
|
.\"
|
|
.\" .AS ?type? ?name?
|
|
.\" Give maximum sizes of arguments for setting tab stops. Type and
|
|
.\" name are examples of largest possible arguments that will be passed
|
|
.\" to .AP later. If args are omitted, default tab stops are used.
|
|
.\"
|
|
.\" .BS
|
|
.\" Start box enclosure. From here until next .BE, everything will be
|
|
.\" enclosed in one large box.
|
|
.\"
|
|
.\" .BE
|
|
.\" End of box enclosure.
|
|
.\"
|
|
.\" .CS
|
|
.\" Begin code excerpt.
|
|
.\"
|
|
.\" .CE
|
|
.\" End code excerpt.
|
|
.\"
|
|
.\" .VS ?version? ?br?
|
|
.\" Begin vertical sidebar, for use in marking newly-changed parts
|
|
.\" of man pages. The first argument is ignored and used for recording
|
|
.\" the version when the .VS was added, so that the sidebars can be
|
|
.\" found and removed when they reach a certain age. If another argument
|
|
.\" is present, then a line break is forced before starting the sidebar.
|
|
.\"
|
|
.\" .VE
|
|
.\" End of vertical sidebar.
|
|
.\"
|
|
.\" .DS
|
|
.\" Begin an indented unfilled display.
|
|
.\"
|
|
.\" .DE
|
|
.\" End of indented unfilled display.
|
|
.\"
|
|
.\" .SO ?manpage?
|
|
.\" Start of list of standard options for a Tk widget. The manpage
|
|
.\" argument defines where to look up the standard options; if
|
|
.\" omitted, defaults to "options". The options follow on successive
|
|
.\" lines, in three columns separated by tabs.
|
|
.\"
|
|
.\" .SE
|
|
.\" End of list of standard options for a Tk widget.
|
|
.\"
|
|
.\" .OP cmdName dbName dbClass
|
|
.\" Start of description of a specific option. cmdName gives the
|
|
.\" option's name as specified in the class command, dbName gives
|
|
.\" the option's name in the option database, and dbClass gives
|
|
.\" the option's class in the option database.
|
|
.\"
|
|
.\" .UL arg1 arg2
|
|
.\" Print arg1 underlined, then print arg2 normally.
|
|
.\"
|
|
.\" .QW arg1 ?arg2?
|
|
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
|
|
.\"
|
|
.\" .PQ arg1 ?arg2?
|
|
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
|
|
.\" (for trailing punctuation) and then a closing parenthesis.
|
|
.\"
|
|
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
|
|
.if t .wh -1.3i ^B
|
|
.nr ^l \n(.l
|
|
.ad b
|
|
.\" # Start an argument description
|
|
.de AP
|
|
.ie !"\\$4"" .TP \\$4
|
|
.el \{\
|
|
. ie !"\\$2"" .TP \\n()Cu
|
|
. el .TP 15
|
|
.\}
|
|
.ta \\n()Au \\n()Bu
|
|
.ie !"\\$3"" \{\
|
|
\&\\$1 \\fI\\$2\\fP (\\$3)
|
|
.\".b
|
|
.\}
|
|
.el \{\
|
|
.br
|
|
.ie !"\\$2"" \{\
|
|
\&\\$1 \\fI\\$2\\fP
|
|
.\}
|
|
.el \{\
|
|
\&\\fI\\$1\\fP
|
|
.\}
|
|
.\}
|
|
..
|
|
.\" # define tabbing values for .AP
|
|
.de AS
|
|
.nr )A 10n
|
|
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
|
|
.nr )B \\n()Au+15n
|
|
.\"
|
|
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
|
|
.nr )C \\n()Bu+\\w'(in/out)'u+2n
|
|
..
|
|
.AS Tcl_Interp Tcl_CreateInterp in/out
|
|
.\" # BS - start boxed text
|
|
.\" # ^y = starting y location
|
|
.\" # ^b = 1
|
|
.de BS
|
|
.br
|
|
.mk ^y
|
|
.nr ^b 1u
|
|
.if n .nf
|
|
.if n .ti 0
|
|
.if n \l'\\n(.lu\(ul'
|
|
.if n .fi
|
|
..
|
|
.\" # BE - end boxed text (draw box now)
|
|
.de BE
|
|
.nf
|
|
.ti 0
|
|
.mk ^t
|
|
.ie n \l'\\n(^lu\(ul'
|
|
.el \{\
|
|
.\" Draw four-sided box normally, but don't draw top of
|
|
.\" box if the box started on an earlier page.
|
|
.ie !\\n(^b-1 \{\
|
|
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
|
|
.\}
|
|
.el \}\
|
|
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
|
|
.\}
|
|
.\}
|
|
.fi
|
|
.br
|
|
.nr ^b 0
|
|
..
|
|
.\" # VS - start vertical sidebar
|
|
.\" # ^Y = starting y location
|
|
.\" # ^v = 1 (for troff; for nroff this doesn't matter)
|
|
.de VS
|
|
.if !"\\$2"" .br
|
|
.mk ^Y
|
|
.ie n 'mc \s12\(br\s0
|
|
.el .nr ^v 1u
|
|
..
|
|
.\" # VE - end of vertical sidebar
|
|
.de VE
|
|
.ie n 'mc
|
|
.el \{\
|
|
.ev 2
|
|
.nf
|
|
.ti 0
|
|
.mk ^t
|
|
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
|
|
.sp -1
|
|
.fi
|
|
.ev
|
|
.\}
|
|
.nr ^v 0
|
|
..
|
|
.\" # Special macro to handle page bottom: finish off current
|
|
.\" # box/sidebar if in box/sidebar mode, then invoked standard
|
|
.\" # page bottom macro.
|
|
.de ^B
|
|
.ev 2
|
|
'ti 0
|
|
'nf
|
|
.mk ^t
|
|
.if \\n(^b \{\
|
|
.\" Draw three-sided box if this is the box's first page,
|
|
.\" draw two sides but no top otherwise.
|
|
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
|
|
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
|
|
.\}
|
|
.if \\n(^v \{\
|
|
.nr ^x \\n(^tu+1v-\\n(^Yu
|
|
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
|
|
.\}
|
|
.bp
|
|
'fi
|
|
.ev
|
|
.if \\n(^b \{\
|
|
.mk ^y
|
|
.nr ^b 2
|
|
.\}
|
|
.if \\n(^v \{\
|
|
.mk ^Y
|
|
.\}
|
|
..
|
|
.\" # DS - begin display
|
|
.de DS
|
|
.RS
|
|
.nf
|
|
.sp
|
|
..
|
|
.\" # DE - end display
|
|
.de DE
|
|
.fi
|
|
.RE
|
|
.sp
|
|
..
|
|
.\" # SO - start of list of standard options
|
|
.de SO
|
|
'ie '\\$1'' .ds So \\fBoptions\\fR
|
|
'el .ds So \\fB\\$1\\fR
|
|
.SH "STANDARD OPTIONS"
|
|
.LP
|
|
.nf
|
|
.ta 5.5c 11c
|
|
.ft B
|
|
..
|
|
.\" # SE - end of list of standard options
|
|
.de SE
|
|
.fi
|
|
.ft R
|
|
.LP
|
|
See the \\*(So manual entry for details on the standard options.
|
|
..
|
|
.\" # OP - start of full description for a single option
|
|
.de OP
|
|
.LP
|
|
.nf
|
|
.ta 4c
|
|
Command-Line Name: \\fB\\$1\\fR
|
|
Database Name: \\fB\\$2\\fR
|
|
Database Class: \\fB\\$3\\fR
|
|
.fi
|
|
.IP
|
|
..
|
|
.\" # CS - begin code excerpt
|
|
.de CS
|
|
.RS
|
|
.nf
|
|
.ta .25i .5i .75i 1i
|
|
..
|
|
.\" # CE - end code excerpt
|
|
.de CE
|
|
.fi
|
|
.RE
|
|
..
|
|
.\" # UL - underline word
|
|
.de UL
|
|
\\$1\l'|0\(ul'\\$2
|
|
..
|
|
.\" # QW - apply quotation marks to word
|
|
.de QW
|
|
.ie '\\*(lq'"' ``\\$1''\\$2
|
|
.\"" fix emacs highlighting
|
|
.el \\*(lq\\$1\\*(rq\\$2
|
|
..
|
|
.\" # PQ - apply parens and quotation marks to word
|
|
.de PQ
|
|
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
|
|
.\"" fix emacs highlighting
|
|
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
|
|
..
|
|
.\" # QR - quoted range
|
|
.de QR
|
|
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
|
|
.\"" fix emacs highlighting
|
|
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
|
|
..
|
|
.\" # MT - "empty" string
|
|
.de MT
|
|
.QW ""
|
|
..
|
|
.BS
|
|
.SH NAME
|
|
ttrace \- Trace-based interpreter initialization
|
|
.SH SYNOPSIS
|
|
package require \fBTcl 8\&.4\fR
|
|
.sp
|
|
package require \fBThread ?2\&.8?\fR
|
|
.sp
|
|
\fBttrace::eval\fR \fIarg\fR ?arg \&.\&.\&.?
|
|
.sp
|
|
\fBttrace::enable\fR
|
|
.sp
|
|
\fBttrace::disable\fR
|
|
.sp
|
|
\fBttrace::cleanup\fR
|
|
.sp
|
|
\fBttrace::update\fR ?epoch?
|
|
.sp
|
|
\fBttrace::getscript\fR
|
|
.sp
|
|
\fBttrace::atenable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::atdisable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::addtrace\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::addscript\fR \fIname\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::addresolver\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::addcleanup\fR \fIbody\fR
|
|
.sp
|
|
\fBttrace::addentry\fR \fIcmd\fR \fIvar\fR \fIval\fR
|
|
.sp
|
|
\fBttrace::getentry\fR \fIcmd\fR \fIvar\fR
|
|
.sp
|
|
\fBttrace::getentries\fR \fIcmd\fR ?pattern?
|
|
.sp
|
|
\fBttrace::delentry\fR \fIcmd\fR
|
|
.sp
|
|
\fBttrace::preload\fR \fIcmd\fR
|
|
.sp
|
|
.BE
|
|
.SH DESCRIPTION
|
|
This package creates a framework for on-demand replication of the
|
|
interpreter state accross threads in an multithreading application\&.
|
|
It relies on the mechanics of Tcl command tracing and the Tcl
|
|
\fBunknown\fR command and mechanism\&.
|
|
.PP
|
|
The package requires Tcl threading extension but can be alternatively
|
|
used stand-alone within the AOLserver, a scalable webserver from
|
|
America Online\&.
|
|
.PP
|
|
In a nutshell, a short sample illustrating the usage of the ttrace
|
|
with the Tcl threading extension:
|
|
.CS
|
|
|
|
|
|
|
|
% package require Ttrace
|
|
2\&.8\&.0
|
|
|
|
% set t1 [thread::create {package require Ttrace; thread::wait}]
|
|
tid0x1802800
|
|
|
|
% ttrace::eval {proc test args {return test-[thread::id]}}
|
|
% thread::send $t1 test
|
|
test-tid0x1802800
|
|
|
|
% set t2 [thread::create {package require Ttrace; thread::wait}]
|
|
tid0x1804000
|
|
|
|
% thread::send $t2 test
|
|
test-tid0x1804000
|
|
|
|
|
|
.CE
|
|
.PP
|
|
As seen from above, the \fBttrace::eval\fR and \fBttrace::update\fR
|
|
commands are used to create a thread-wide definition of a simple
|
|
Tcl procedure and replicate that definition to all, already existing
|
|
or later created, threads\&.
|
|
.SH "USER COMMANDS"
|
|
This section describes user-level commands\&. Those commands can be
|
|
used by script writers to control the execution of the tracing
|
|
framework\&.
|
|
.TP
|
|
\fBttrace::eval\fR \fIarg\fR ?arg \&.\&.\&.?
|
|
This command concatenates given arguments and evaluates the resulting
|
|
Tcl command with trace framework enabled\&. If the command execution
|
|
was ok, it takes necessary steps to automatically propagate the
|
|
trace epoch change to all threads in the application\&.
|
|
For AOLserver, only newly created threads actually receive the
|
|
epoch change\&. For the Tcl threading extension, all threads created by
|
|
the extension are automatically updated\&. If the command execution
|
|
resulted in Tcl error, no state propagation takes place\&.
|
|
.sp
|
|
This is the most important user-level command of the package as
|
|
it wraps most of the commands described below\&. This greatly
|
|
simplifies things, because user need to learn just this (one)
|
|
command in order to effectively use the package\&. Other commands,
|
|
as desribed below, are included mostly for the sake of completeness\&.
|
|
.TP
|
|
\fBttrace::enable\fR
|
|
Activates all registered callbacks in the framework
|
|
and starts a new trace epoch\&. The trace epoch encapsulates all
|
|
changes done to the interpreter during the time traces are activated\&.
|
|
.TP
|
|
\fBttrace::disable\fR
|
|
Deactivates all registered callbacks in the framework
|
|
and closes the current trace epoch\&.
|
|
.TP
|
|
\fBttrace::cleanup\fR
|
|
Used to clean-up all on-demand loaded resources in the interpreter\&.
|
|
It effectively brings Tcl interpreter to its pristine state\&.
|
|
.TP
|
|
\fBttrace::update\fR ?epoch?
|
|
Used to refresh the state of the interpreter to match the optional
|
|
trace ?epoch?\&. If the optional ?epoch? is not given, it takes
|
|
the most recent trace epoch\&.
|
|
.TP
|
|
\fBttrace::getscript\fR
|
|
Returns a synthetized Tcl script which may be sourced in any interpreter\&.
|
|
This script sets the stage for the Tcl \fBunknown\fR command so it can
|
|
load traced resources from the in-memory database\&. Normally, this command
|
|
is automatically invoked by other higher-level commands like
|
|
\fBttrace::eval\fR and \fBttrace::update\fR\&.
|
|
.PP
|
|
.SH "CALLBACK COMMANDS"
|
|
A word upfront: the package already includes callbacks for tracing
|
|
following Tcl commands: \fBproc\fR, \fBnamespace\fR, \fBvariable\fR,
|
|
\fBload\fR, and \fBrename\fR\&. Additionaly, a set of callbacks for
|
|
tracing resources (object, clasess) for the XOTcl v1\&.3\&.8+, an
|
|
OO-extension to Tcl, is also provided\&.
|
|
This gives a solid base for solving most of the real-life needs and
|
|
serves as an example for people wanting to customize the package
|
|
to cover their specific needs\&.
|
|
.PP
|
|
Below, you can find commands for registering callbacks in the
|
|
framework and for writing callback scripts\&. These callbacks are
|
|
invoked by the framework in order to gather interpreter state
|
|
changes, build in-memory database, perform custom-cleanups and
|
|
various other tasks\&.
|
|
.TP
|
|
\fBttrace::atenable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
Registers Tcl callback to be activated at \fBttrace::enable\fR\&.
|
|
Registered callbacks are activated on FIFO basis\&. The callback
|
|
definition includes the name of the callback, \fIcmd\fR, a list
|
|
of callback arguments, \fIarglist\fR and the \fIbody\fR of the
|
|
callback\&. Effectively, this actually resembles the call interface
|
|
of the standard Tcl \fBproc\fR command\&.
|
|
.TP
|
|
\fBttrace::atdisable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
Registers Tcl callback to be activated at \fBttrace::disable\fR\&.
|
|
Registered callbacks are activated on FIFO basis\&. The callback
|
|
definition includes the name of the callback, \fIcmd\fR, a list
|
|
of callback arguments, \fIarglist\fR and the \fIbody\fR of the
|
|
callback\&. Effectively, this actually resembles the call interface
|
|
of the standard Tcl \fBproc\fR command\&.
|
|
.TP
|
|
\fBttrace::addtrace\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
Registers Tcl callback to be activated for tracing the Tcl
|
|
\fBcmd\fR command\&. The callback definition includes the name of
|
|
the Tcl command to trace, \fIcmd\fR, a list of callback arguments,
|
|
\fIarglist\fR and the \fIbody\fR of the callback\&. Effectively,
|
|
this actually resembles the call interface of the standard Tcl
|
|
\fBproc\fR command\&.
|
|
.TP
|
|
\fBttrace::addscript\fR \fIname\fR \fIbody\fR
|
|
Registers Tcl callback to be activated for building a Tcl
|
|
script to be passed to other interpreters\&. This script is
|
|
used to set the stage for the Tcl \fBunknown\fR command\&.
|
|
Registered callbacks are activated on FIFO basis\&.
|
|
The callback definition includes the name of the callback,
|
|
\fIname\fR and the \fIbody\fR of the callback\&.
|
|
.TP
|
|
\fBttrace::addresolver\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
|
|
Registers Tcl callback to be activated by the overloaded Tcl
|
|
\fBunknown\fR command\&.
|
|
Registered callbacks are activated on FIFO basis\&.
|
|
This callback is used to resolve the resource and load the
|
|
resource in the current interpreter\&.
|
|
.TP
|
|
\fBttrace::addcleanup\fR \fIbody\fR
|
|
Registers Tcl callback to be activated by the \fBtrace::cleanup\fR\&.
|
|
Registered callbacks are activated on FIFO basis\&.
|
|
.TP
|
|
\fBttrace::addentry\fR \fIcmd\fR \fIvar\fR \fIval\fR
|
|
Adds one entry to the named in-memory database\&.
|
|
.TP
|
|
\fBttrace::getentry\fR \fIcmd\fR \fIvar\fR
|
|
Returns the value of the entry from the named in-memory database\&.
|
|
.TP
|
|
\fBttrace::getentries\fR \fIcmd\fR ?pattern?
|
|
Returns names of all entries from the named in-memory database\&.
|
|
.TP
|
|
\fBttrace::delentry\fR \fIcmd\fR
|
|
Deletes an entry from the named in-memory database\&.
|
|
.TP
|
|
\fBttrace::preload\fR \fIcmd\fR
|
|
Registers the Tcl command to be loaded in the interpreter\&.
|
|
Commands registered this way will always be the part of
|
|
the interpreter and not be on-demand loaded by the Tcl
|
|
\fBunknown\fR command\&.
|
|
.PP
|
|
.SH DISCUSSION
|
|
Common introspective state-replication approaches use a custom Tcl
|
|
script to introspect the running interpreter and synthesize another
|
|
Tcl script to replicate this state in some other interpreter\&.
|
|
This package, on the contrary, uses Tcl command traces\&. Command
|
|
traces are registered on selected Tcl commands, like \fBproc\fR,
|
|
\fBnamespace\fR, \fBload\fR and other standard (and/or user-defined)
|
|
Tcl commands\&. When activated, those traces build an in-memory
|
|
database of created resources\&. This database is used as a resource
|
|
repository for the (overloaded) Tcl \fBunknown\fR command which
|
|
creates the requested resource in the interpreter on demand\&.
|
|
This way, users can update just one interpreter (master) in one
|
|
thread and replicate that interpreter state (or part of it) to other
|
|
threads/interpreters in the process\&.
|
|
.PP
|
|
Immediate benefit of such approach is the much smaller memory footprint
|
|
of the application and much faster thread creation\&. By not actually
|
|
loading all necessary procedures (and other resources) in every thread
|
|
at the thread initialization time, but by deffering this to the time the
|
|
resource is actually referenced, significant improvements in both
|
|
memory consumption and thread initialization time can be achieved\&. Some
|
|
tests have shown that memory footprint of an multithreading Tcl application
|
|
went down more than three times and thread startup time was reduced for
|
|
about 50 times\&. Note that your mileage may vary\&.
|
|
Other benefits include much finer control about what (and when) gets
|
|
replicated from the master to other Tcl thread/interpreters\&.
|
|
.SH "SEE ALSO"
|
|
thread, tpool, tsv
|
|
.SH KEYWORDS
|
|
command tracing, introspection
|