+++ /dev/null
-'\"
-'\" Generated from file '' by tcllib/doctools with format 'nroff'
-'\"
-'\" -*- tcl -*- doctools manpage
-'\" The 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
-'\" Start of list of standard options for a Tk widget. The
-'\" options follow on successive lines, in four 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.
-'\"
-'\" # 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
-.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 \\fBoptions\\fR 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
-.if t .ft C
-..
-'\" # CE - end code excerpt
-.de CE
-.fi
-.if t .ft R
-.RE
-..
-.de UL
-\\$1\l'|0\(ul'\\$2
-..
-
-.TH "ttrace" n 2.7 "Tcl Threading"
-.BS
-.SH "NAME"
-ttrace \- Trace-based interpreter initialization
-.SH "SYNOPSIS"
-package require \fBTcl 8.4\fR
-.sp
-package require \fBThread ?2.7?\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:
-.nf
-
- % package require Ttrace
- 2.7.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
-
-.fi
-.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.
-.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.
-.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
OSDN Git Service
