1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin ttrace n 2.8] 3[moddesc {Tcl Threading}] 4[titledesc {Trace-based interpreter initialization}] 5[require Tcl 8.4] 6[require Thread [opt 2.8]] 7 8[description] 9This package creates a framework for on-demand replication of the 10interpreter state across threads in an multithreading application. 11It relies on the mechanics of Tcl command tracing and the Tcl 12[cmd unknown] command and mechanism. 13[para] 14The package requires Tcl threading extension but can be alternatively 15used stand-alone within the AOLserver, a scalable webserver from 16America Online. 17[para] 18In a nutshell, a short sample illustrating the usage of the ttrace 19with the Tcl threading extension: 20 21[example { 22 23 % package require Ttrace 24 2.8.2 25 26 % set t1 [thread::create {package require Ttrace; thread::wait}] 27 tid0x1802800 28 29 % ttrace::eval {proc test args {return test-[thread::id]}} 30 % thread::send $t1 test 31 test-tid0x1802800 32 33 % set t2 [thread::create {package require Ttrace; thread::wait}] 34 tid0x1804000 35 36 % thread::send $t2 test 37 test-tid0x1804000 38 39}] 40[para] 41As seen from above, the [cmd ttrace::eval] and [cmd ttrace::update] 42commands are used to create a thread-wide definition of a simple 43Tcl procedure and replicate that definition to all, already existing 44or later created, threads. 45 46[section {USER COMMANDS}] 47This section describes user-level commands. Those commands can be 48used by script writers to control the execution of the tracing 49framework. 50 51[list_begin definitions] 52 53[call [cmd ttrace::eval] [arg arg] [opt {arg ...}]] 54 55This command concatenates given arguments and evaluates the resulting 56Tcl command with trace framework enabled. If the command execution 57was ok, it takes necessary steps to automatically propagate the 58trace epoch change to all threads in the application. 59For AOLserver, only newly created threads actually receive the 60epoch change. For the Tcl threading extension, all threads created by 61the extension are automatically updated. If the command execution 62resulted in Tcl error, no state propagation takes place. 63[para] 64This is the most important user-level command of the package as 65it wraps most of the commands described below. This greatly 66simplifies things, because user need to learn just this (one) 67command in order to effectively use the package. Other commands, 68as described below, are included mostly for the sake of completeness. 69 70[call [cmd ttrace::enable]] 71 72Activates all registered callbacks in the framework 73and starts a new trace epoch. The trace epoch encapsulates all 74changes done to the interpreter during the time traces are activated. 75 76[call [cmd ttrace::disable]] 77 78Deactivates all registered callbacks in the framework 79and closes the current trace epoch. 80 81[call [cmd ttrace::cleanup]] 82 83Used to clean-up all on-demand loaded resources in the interpreter. 84It effectively brings Tcl interpreter to its pristine state. 85 86[call [cmd ttrace::update] [opt epoch]] 87 88Used to refresh the state of the interpreter to match the optional 89trace [opt epoch]. If the optional [opt epoch] is not given, it takes 90the most recent trace epoch. 91 92[call [cmd ttrace::getscript]] 93 94Returns a synthesized Tcl script which may be sourced in any interpreter. 95This script sets the stage for the Tcl [cmd unknown] command so it can 96load traced resources from the in-memory database. Normally, this command 97is automatically invoked by other higher-level commands like 98[cmd ttrace::eval] and [cmd ttrace::update]. 99 100[list_end] 101 102[section {CALLBACK COMMANDS}] 103A word upfront: the package already includes callbacks for tracing 104following Tcl commands: [cmd proc], [cmd namespace], [cmd variable], 105[cmd load], and [cmd rename]. Additionally, a set of callbacks for 106tracing resources (object, classes) for the XOTcl v1.3.8+, an 107OO-extension to Tcl, is also provided. 108This gives a solid base for solving most of the real-life needs and 109serves as an example for people wanting to customize the package 110to cover their specific needs. 111[para] 112Below, you can find commands for registering callbacks in the 113framework and for writing callback scripts. These callbacks are 114invoked by the framework in order to gather interpreter state 115changes, build in-memory database, perform custom-cleanups and 116various other tasks. 117 118 119[list_begin definitions] 120 121[call [cmd ttrace::atenable] [arg cmd] [arg arglist] [arg body]] 122 123Registers Tcl callback to be activated at [cmd ttrace::enable]. 124Registered callbacks are activated on FIFO basis. The callback 125definition includes the name of the callback, [arg cmd], a list 126of callback arguments, [arg arglist] and the [arg body] of the 127callback. Effectively, this actually resembles the call interface 128of the standard Tcl [cmd proc] command. 129 130 131[call [cmd ttrace::atdisable] [arg cmd] [arg arglist] [arg body]] 132 133Registers Tcl callback to be activated at [cmd ttrace::disable]. 134Registered callbacks are activated on FIFO basis. The callback 135definition includes the name of the callback, [arg cmd], a list 136of callback arguments, [arg arglist] and the [arg body] of the 137callback. Effectively, this actually resembles the call interface 138of the standard Tcl [cmd proc] command. 139 140 141[call [cmd ttrace::addtrace] [arg cmd] [arg arglist] [arg body]] 142 143Registers Tcl callback to be activated for tracing the Tcl 144[cmd cmd] command. The callback definition includes the name of 145the Tcl command to trace, [arg cmd], a list of callback arguments, 146[arg arglist] and the [arg body] of the callback. Effectively, 147this actually resembles the call interface of the standard Tcl 148[cmd proc] command. 149 150 151[call [cmd ttrace::addscript] [arg name] [arg body]] 152 153Registers Tcl callback to be activated for building a Tcl 154script to be passed to other interpreters. This script is 155used to set the stage for the Tcl [cmd unknown] command. 156Registered callbacks are activated on FIFO basis. 157The callback definition includes the name of the callback, 158[arg name] and the [arg body] of the callback. 159 160[call [cmd ttrace::addresolver] [arg cmd] [arg arglist] [arg body]] 161 162Registers Tcl callback to be activated by the overloaded Tcl 163[cmd unknown] command. 164Registered callbacks are activated on FIFO basis. 165This callback is used to resolve the resource and load the 166resource in the current interpreter. 167 168[call [cmd ttrace::addcleanup] [arg body]] 169 170Registers Tcl callback to be activated by the [cmd trace::cleanup]. 171Registered callbacks are activated on FIFO basis. 172 173[call [cmd ttrace::addentry] [arg cmd] [arg var] [arg val]] 174 175Adds one entry to the named in-memory database. 176 177[call [cmd ttrace::getentry] [arg cmd] [arg var]] 178 179Returns the value of the entry from the named in-memory database. 180 181[call [cmd ttrace::getentries] [arg cmd] [opt pattern]] 182 183Returns names of all entries from the named in-memory database. 184 185[call [cmd ttrace::delentry] [arg cmd]] 186 187Deletes an entry from the named in-memory database. 188 189[call [cmd ttrace::preload] [arg cmd]] 190 191Registers the Tcl command to be loaded in the interpreter. 192Commands registered this way will always be the part of 193the interpreter and not be on-demand loaded by the Tcl 194[cmd unknown] command. 195 196[list_end] 197 198[section DISCUSSION] 199Common introspective state-replication approaches use a custom Tcl 200script to introspect the running interpreter and synthesize another 201Tcl script to replicate this state in some other interpreter. 202This package, on the contrary, uses Tcl command traces. Command 203traces are registered on selected Tcl commands, like [cmd proc], 204[cmd namespace], [cmd load] and other standard (and/or user-defined) 205Tcl commands. When activated, those traces build an in-memory 206database of created resources. This database is used as a resource 207repository for the (overloaded) Tcl [cmd unknown] command which 208creates the requested resource in the interpreter on demand. 209This way, users can update just one interpreter (master) in one 210thread and replicate that interpreter state (or part of it) to other 211threads/interpreters in the process. 212[para] 213Immediate benefit of such approach is the much smaller memory footprint 214of the application and much faster thread creation. By not actually 215loading all necessary procedures (and other resources) in every thread 216at the thread initialization time, but by deferring this to the time the 217resource is actually referenced, significant improvements in both 218memory consumption and thread initialization time can be achieved. Some 219tests have shown that memory footprint of an multithreading Tcl application 220went down more than three times and thread startup time was reduced for 221about 50 times. Note that your mileage may vary. 222 223Other benefits include much finer control about what (and when) gets 224replicated from the master to other Tcl thread/interpreters. 225 226[see_also tsv tpool thread] 227 228[keywords {command tracing} introspection] 229 230[manpage_end] 231