| <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> | |