--- /dev/null
+
+<html><head>
+<title>ttrace - Tcl Threading</title>
+<style type="text/css"><!--
+ HTML {
+ background: #FFFFFF;
+ color: black;
+ }
+ BODY {
+ background: #FFFFFF;
+ color: black;
+ }
+ DIV.doctools {
+ margin-left: 10%;
+ margin-right: 10%;
+ }
+ DIV.doctools H1,DIV.doctools H2 {
+ margin-left: -5%;
+ }
+ H1, H2, H3, H4 {
+ margin-top: 1em;
+ font-family: sans-serif;
+ font-size: large;
+ color: #005A9C;
+ background: transparent;
+ text-align: left;
+ }
+ H1.doctools_title {
+ text-align: center;
+ }
+ UL,OL {
+ margin-right: 0em;
+ margin-top: 3pt;
+ margin-bottom: 3pt;
+ }
+ UL LI {
+ list-style: disc;
+ }
+ OL LI {
+ list-style: decimal;
+ }
+ DT {
+ padding-top: 1ex;
+ }
+ UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
+ font: normal 12pt/14pt sans-serif;
+ list-style: none;
+ }
+ LI.doctools_section, LI.doctools_subsection {
+ list-style: none;
+ margin-left: 0em;
+ text-indent: 0em;
+ padding: 0em;
+ }
+ PRE {
+ display: block;
+ font-family: monospace;
+ white-space: pre;
+ margin: 0%;
+ padding-top: 0.5ex;
+ padding-bottom: 0.5ex;
+ padding-left: 1ex;
+ padding-right: 1ex;
+ width: 100%;
+ }
+ PRE.doctools_example {
+ color: black;
+ background: #f5dcb3;
+ border: 1px solid black;
+ }
+ UL.doctools_requirements LI, UL.doctools_syntax LI {
+ list-style: none;
+ margin-left: 0em;
+ text-indent: 0em;
+ padding: 0em;
+ }
+ DIV.doctools_synopsis {
+ color: black;
+ background: #80ffff;
+ border: 1px solid black;
+ font-family: serif;
+ margin-top: 1em;
+ margin-bottom: 1em;
+ }
+ UL.doctools_syntax {
+ margin-top: 1em;
+ border-top: 1px solid black;
+ }
+ UL.doctools_requirements {
+ margin-bottom: 1em;
+ border-bottom: 1px solid black;
+ }
+--></style>
+</head>
+<! -- Generated from file '' by tcllib/doctools with format 'html'
+ -->
+<! -- ttrace.n
+ -->
+<body><div class="doctools">
+<h1 class="doctools_title">ttrace(n) 2.8 "Tcl Threading"</h1>
+<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
+<p>ttrace - Trace-based interpreter initialization</p>
+</div>
+<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
+<ul class="doctools_toc">
+<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
+<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
+<li class="doctools_section"><a href="#section1">Description</a></li>
+<li class="doctools_section"><a href="#section2">USER COMMANDS</a></li>
+<li class="doctools_section"><a href="#section3">CALLBACK COMMANDS</a></li>
+<li class="doctools_section"><a href="#section4">DISCUSSION</a></li>
+<li class="doctools_section"><a href="#see-also">See Also</a></li>
+<li class="doctools_section"><a href="#keywords">Keywords</a></li>
+</ul>
+</div>
+<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
+<div class="doctools_synopsis">
+<ul class="doctools_requirements">
+<li>package require <b class="pkgname">Tcl 8.4</b></li>
+<li>package require <b class="pkgname">Thread <span class="opt">?2.8?</span></b></li>
+</ul>
+<ul class="doctools_syntax">
+<li><a href="#1"><b class="cmd">ttrace::eval</b> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></li>
+<li><a href="#2"><b class="cmd">ttrace::enable</b></a></li>
+<li><a href="#3"><b class="cmd">ttrace::disable</b></a></li>
+<li><a href="#4"><b class="cmd">ttrace::cleanup</b></a></li>
+<li><a href="#5"><b class="cmd">ttrace::update</b> <span class="opt">?epoch?</span></a></li>
+<li><a href="#6"><b class="cmd">ttrace::getscript</b></a></li>
+<li><a href="#7"><b class="cmd">ttrace::atenable</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
+<li><a href="#8"><b class="cmd">ttrace::atdisable</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
+<li><a href="#9"><b class="cmd">ttrace::addtrace</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
+<li><a href="#10"><b class="cmd">ttrace::addscript</b> <i class="arg">name</i> <i class="arg">body</i></a></li>
+<li><a href="#11"><b class="cmd">ttrace::addresolver</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
+<li><a href="#12"><b class="cmd">ttrace::addcleanup</b> <i class="arg">body</i></a></li>
+<li><a href="#13"><b class="cmd">ttrace::addentry</b> <i class="arg">cmd</i> <i class="arg">var</i> <i class="arg">val</i></a></li>
+<li><a href="#14"><b class="cmd">ttrace::getentry</b> <i class="arg">cmd</i> <i class="arg">var</i></a></li>
+<li><a href="#15"><b class="cmd">ttrace::getentries</b> <i class="arg">cmd</i> <span class="opt">?pattern?</span></a></li>
+<li><a href="#16"><b class="cmd">ttrace::delentry</b> <i class="arg">cmd</i></a></li>
+<li><a href="#17"><b class="cmd">ttrace::preload</b> <i class="arg">cmd</i></a></li>
+</ul>
+</div>
+</div>
+<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
+<p>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
+<b class="cmd">unknown</b> command and mechanism.</p>
+<p>The package requires Tcl threading extension but can be alternatively
+used stand-alone within the AOLserver, a scalable webserver from
+America Online.</p>
+<p>In a nutshell, a short sample illustrating the usage of the ttrace
+with the Tcl threading extension:</p>
+<pre class="doctools_example">
+ % package require Ttrace
+ 2.8.2
+ % 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
+</pre>
+<p>As seen from above, the <b class="cmd">ttrace::eval</b> and <b class="cmd">ttrace::update</b>
+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.</p>
+</div>
+<div id="section2" class="doctools_section"><h2><a name="section2">USER COMMANDS</a></h2>
+<p>This section describes user-level commands. Those commands can be
+used by script writers to control the execution of the tracing
+framework.</p>
+<dl class="doctools_definitions">
+<dt><a name="1"><b class="cmd">ttrace::eval</b> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></dt>
+<dd><p>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.</p>
+<p>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.</p></dd>
+<dt><a name="2"><b class="cmd">ttrace::enable</b></a></dt>
+<dd><p>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.</p></dd>
+<dt><a name="3"><b class="cmd">ttrace::disable</b></a></dt>
+<dd><p>Deactivates all registered callbacks in the framework
+and closes the current trace epoch.</p></dd>
+<dt><a name="4"><b class="cmd">ttrace::cleanup</b></a></dt>
+<dd><p>Used to clean-up all on-demand loaded resources in the interpreter.
+It effectively brings Tcl interpreter to its pristine state.</p></dd>
+<dt><a name="5"><b class="cmd">ttrace::update</b> <span class="opt">?epoch?</span></a></dt>
+<dd><p>Used to refresh the state of the interpreter to match the optional
+trace <span class="opt">?epoch?</span>. If the optional <span class="opt">?epoch?</span> is not given, it takes
+the most recent trace epoch.</p></dd>
+<dt><a name="6"><b class="cmd">ttrace::getscript</b></a></dt>
+<dd><p>Returns a synthetized Tcl script which may be sourced in any interpreter.
+This script sets the stage for the Tcl <b class="cmd">unknown</b> command so it can
+load traced resources from the in-memory database. Normally, this command
+is automatically invoked by other higher-level commands like
+<b class="cmd">ttrace::eval</b> and <b class="cmd">ttrace::update</b>.</p></dd>
+</dl>
+</div>
+<div id="section3" class="doctools_section"><h2><a name="section3">CALLBACK COMMANDS</a></h2>
+<p>A word upfront: the package already includes callbacks for tracing
+following Tcl commands: <b class="cmd">proc</b>, <b class="cmd">namespace</b>, <b class="cmd">variable</b>,
+<b class="cmd">load</b>, and <b class="cmd">rename</b>. 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.</p>
+<p>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.</p>
+<dl class="doctools_definitions">
+<dt><a name="7"><b class="cmd">ttrace::atenable</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
+<dd><p>Registers Tcl callback to be activated at <b class="cmd">ttrace::enable</b>.
+Registered callbacks are activated on FIFO basis. The callback
+definition includes the name of the callback, <i class="arg">cmd</i>, a list
+of callback arguments, <i class="arg">arglist</i> and the <i class="arg">body</i> of the
+callback. Effectively, this actually resembles the call interface
+of the standard Tcl <b class="cmd">proc</b> command.</p></dd>
+<dt><a name="8"><b class="cmd">ttrace::atdisable</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
+<dd><p>Registers Tcl callback to be activated at <b class="cmd">ttrace::disable</b>.
+Registered callbacks are activated on FIFO basis. The callback
+definition includes the name of the callback, <i class="arg">cmd</i>, a list
+of callback arguments, <i class="arg">arglist</i> and the <i class="arg">body</i> of the
+callback. Effectively, this actually resembles the call interface
+of the standard Tcl <b class="cmd">proc</b> command.</p></dd>
+<dt><a name="9"><b class="cmd">ttrace::addtrace</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
+<dd><p>Registers Tcl callback to be activated for tracing the Tcl
+<b class="cmd">cmd</b> command. The callback definition includes the name of
+the Tcl command to trace, <i class="arg">cmd</i>, a list of callback arguments,
+<i class="arg">arglist</i> and the <i class="arg">body</i> of the callback. Effectively,
+this actually resembles the call interface of the standard Tcl
+<b class="cmd">proc</b> command.</p></dd>
+<dt><a name="10"><b class="cmd">ttrace::addscript</b> <i class="arg">name</i> <i class="arg">body</i></a></dt>
+<dd><p>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 <b class="cmd">unknown</b> command.
+Registered callbacks are activated on FIFO basis.
+The callback definition includes the name of the callback,
+<i class="arg">name</i> and the <i class="arg">body</i> of the callback.</p></dd>
+<dt><a name="11"><b class="cmd">ttrace::addresolver</b> <i class="arg">cmd</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
+<dd><p>Registers Tcl callback to be activated by the overloaded Tcl
+<b class="cmd">unknown</b> command.
+Registered callbacks are activated on FIFO basis.
+This callback is used to resolve the resource and load the
+resource in the current interpreter.</p></dd>
+<dt><a name="12"><b class="cmd">ttrace::addcleanup</b> <i class="arg">body</i></a></dt>
+<dd><p>Registers Tcl callback to be activated by the <b class="cmd">trace::cleanup</b>.
+Registered callbacks are activated on FIFO basis.</p></dd>
+<dt><a name="13"><b class="cmd">ttrace::addentry</b> <i class="arg">cmd</i> <i class="arg">var</i> <i class="arg">val</i></a></dt>
+<dd><p>Adds one entry to the named in-memory database.</p></dd>
+<dt><a name="14"><b class="cmd">ttrace::getentry</b> <i class="arg">cmd</i> <i class="arg">var</i></a></dt>
+<dd><p>Returns the value of the entry from the named in-memory database.</p></dd>
+<dt><a name="15"><b class="cmd">ttrace::getentries</b> <i class="arg">cmd</i> <span class="opt">?pattern?</span></a></dt>
+<dd><p>Returns names of all entries from the named in-memory database.</p></dd>
+<dt><a name="16"><b class="cmd">ttrace::delentry</b> <i class="arg">cmd</i></a></dt>
+<dd><p>Deletes an entry from the named in-memory database.</p></dd>
+<dt><a name="17"><b class="cmd">ttrace::preload</b> <i class="arg">cmd</i></a></dt>
+<dd><p>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
+<b class="cmd">unknown</b> command.</p></dd>
+</dl>
+</div>
+<div id="section4" class="doctools_section"><h2><a name="section4">DISCUSSION</a></h2>
+<p>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 <b class="cmd">proc</b>,
+<b class="cmd">namespace</b>, <b class="cmd">load</b> 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 <b class="cmd">unknown</b> 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.</p>
+<p>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.</p>
+</div>
+<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
+<p>thread, tpool, tsv</p>
+</div>
+<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
+<p>command tracing, introspection</p>
+</div>
+</div></body></html>
+
OSDN Git Service
