1ttrace(n) ttrace(n)
3______________________________________________________________________________
7
9 ttrace - Trace-based interpreter initialization
10
12 package require Tcl 8.4
13 package require Thread ?2.6?
15 ttrace::eval arg ?arg ...?
17 ttrace::enable
19 ttrace::disable
21 ttrace::cleanup
23 ttrace::update ?epoch?
25 ttrace::getscript
27 ttrace::atenable cmd arglist body
29 ttrace::atdisable cmd arglist body
31 ttrace::addtrace cmd arglist body
33 ttrace::addscript name body
35 ttrace::addresolver cmd arglist body
37 ttrace::addcleanup body
39 ttrace::addentry cmd var val
41 ttrace::getentry cmd var
43 ttrace::getentries cmd ?pattern?
45 ttrace::delentry cmd
47 ttrace::preload cmd
49_________________________________________________________________
51
53 This package creates a framework for on-demand replication of the
54 interpreter state accross threads in an multithreading application. It
55 relies on the mechanics of Tcl command tracing and the Tcl unknown com‐
56 mand and mechanism.
57 The package requires Tcl threading extension but can be alternatively
59 used stand-alone within the AOLserver, a scalable webserver from Amer‐
60 ica Online.
61 In a nutshell, a short sample illustrating the usage of the ttrace with
63 the Tcl threading extension:
64 % package require Ttrace
66 2.6.5
67 % set t1 [thread::create {package require Ttrace; thread::wait}]
69 tid0x1802800
70 % ttrace::eval {proc test args {return test-[thread::id]}}
72 % thread::send $t1 test
73 test-tid0x1802800
74 % set t2 [thread::create {package require Ttrace; thread::wait}]
76 tid0x1804000
77 % thread::send $t2 test
79 test-tid0x1804000
80 As seen from above, the ttrace::eval and ttrace::update commands are
83 used to create a thread-wide definition of a simple Tcl procedure and
84 replicate that definition to all, already existing or later created,
85 threads.
86
88 This section describes user-level commands. Those commands can be used
89 by script writers to control the execution of the tracing framework.
90 ttrace::eval arg ?arg ...?
92 This command concatenates given arguments and evaluates the
93 resulting Tcl command with trace framework enabled. If the com‐
94 mand execution was ok, it takes necessary steps to automatically
95 propagate the trace epoch change to all threads in the applica‐
96 tion. For AOLserver, only newly created threads actually
97 receive the epoch change. For the Tcl threading extension, all
98 threads created by the extension are automatically updated. If
99 the command execution resulted in Tcl error, no state propaga‐
100 tion takes place.
101 This is the most important user-level command of the package as
103 it wraps most of the commands described below. This greatly sim‐
104 plifies things, because user need to learn just this (one) com‐
105 mand in order to effectively use the package. Other commands, as
106 desribed below, are included mostly for the sake of complete‐
107 ness.
108 ttrace::enable
110 Activates all registered callbacks in the framework and starts a
111 new trace epoch. The trace epoch encapsulates all changes done
112 to the interpreter during the time traces are activated.
113 ttrace::disable
115 Deactivates all registered callbacks in the framework and closes
116 the current trace epoch.
117 ttrace::cleanup
119 Used to clean-up all on-demand loaded resources in the inter‐
120 preter. It effectively brings Tcl interpreter to its pristine
121 state.
122 ttrace::update ?epoch?
124 Used to refresh the state of the interpreter to match the
125 optional trace ?epoch?. If the optional ?epoch? is not given, it
126 takes the most recent trace epoch.
127 ttrace::getscript
129 Returns a synthetized Tcl script which may be sourced in any
130 interpreter. This script sets the stage for the Tcl unknown
131 command so it can load traced resources from the in-memory data‐
132 base. Normally, this command is automatically invoked by other
133 higher-level commands like ttrace::eval and ttrace::update.
134
136 A word upfront: the package already includes callbacks for tracing fol‐
137 lowing Tcl commands: proc, namespace, variable, load, and rename. Addi‐
138 tionaly, a set of callbacks for tracing resources (object, clasess) for
139 the XOTcl v1.3.8+, an OO-extension to Tcl, is also provided. This
140 gives a solid base for solving most of the real-life needs and serves
141 as an example for people wanting to customize the package to cover
142 their specific needs.
143 Below, you can find commands for registering callbacks in the framework
145 and for writing callback scripts. These callbacks are invoked by the
146 framework in order to gather interpreter state changes, build in-memory
147 database, perform custom-cleanups and various other tasks.
148 ttrace::atenable cmd arglist body
150 Registers Tcl callback to be activated at ttrace::enable. Reg‐
151 istered callbacks are activated on FIFO basis. The callback def‐
152 inition includes the name of the callback, cmd, a list of call‐
153 back arguments, arglist and the body of the callback. Effec‐
154 tively, this actually resembles the call interface of the stan‐
155 dard Tcl proc command.
156 ttrace::atdisable cmd arglist body
158 Registers Tcl callback to be activated at ttrace::disable. Reg‐
159 istered callbacks are activated on FIFO basis. The callback def‐
160 inition includes the name of the callback, cmd, a list of call‐
161 back arguments, arglist and the body of the callback. Effec‐
162 tively, this actually resembles the call interface of the stan‐
163 dard Tcl proc command.
164 ttrace::addtrace cmd arglist body
166 Registers Tcl callback to be activated for tracing the Tcl cmd
167 command. The callback definition includes the name of the Tcl
168 command to trace, cmd, a list of callback arguments, arglist and
169 the body of the callback. Effectively, this actually resembles
170 the call interface of the standard Tcl proc command.
171 ttrace::addscript name body
173 Registers Tcl callback to be activated for building a Tcl script
174 to be passed to other interpreters. This script is used to set
175 the stage for the Tcl unknown command. Registered callbacks are
176 activated on FIFO basis. The callback definition includes the
177 name of the callback, name and the body of the callback.
178 ttrace::addresolver cmd arglist body
180 Registers Tcl callback to be activated by the overloaded Tcl
181 unknown command. Registered callbacks are activated on FIFO
182 basis. This callback is used to resolve the resource and load
183 the resource in the current interpreter.
184 ttrace::addcleanup body
186 Registers Tcl callback to be activated by the trace::cleanup.
187 Registered callbacks are activated on FIFO basis.
188 ttrace::addentry cmd var val
190 Adds one entry to the named in-memory database.
191 ttrace::getentry cmd var
193 Returns the value of the entry from the named in-memory data‐
194 base.
195 ttrace::getentries cmd ?pattern?
197 Returns names of all entries from the named in-memory database.
198 ttrace::delentry cmd
200 Deletes an entry from the named in-memory database.
201 ttrace::preload cmd
203 Registers the Tcl command to be loaded in the interpreter. Com‐
204 mands registered this way will always be the part of the inter‐
205 preter and not be on-demand loaded by the Tcl unknown command.
206
208 Common introspective state-replication approaches use a custom Tcl
209 script to introspect the running interpreter and synthesize another Tcl
210 script to replicate this state in some other interpreter. This pack‐
211 age, on the contrary, uses Tcl command traces. Command traces are reg‐
212 istered on selected Tcl commands, like proc, namespace, load and other
213 standard (and/or user-defined) Tcl commands. When activated, those
214 traces build an in-memory database of created resources. This database
215 is used as a resource repository for the (overloaded) Tcl unknown com‐
216 mand which creates the requested resource in the interpreter on demand.
217 This way, users can update just one interpreter (master) in one thread
218 and replicate that interpreter state (or part of it) to other
219 threads/interpreters in the process.
220 Immediate benefit of such approach is the much smaller memory footprint
222 of the application and much faster thread creation. By not actually
223 loading all necessary procedures (and other resources) in every thread
224 at the thread initialization time, but by deffering this to the time
225 the resource is actually referenced, significant improvements in both
226 memory consumption and thread initialization time can be achieved. Some
227 tests have shown that memory footprint of an multithreading Tcl appli‐
228 cation went down more than three times and thread startup time was
229 reduced for about 50 times. Note that your mileage may vary. Other
230 benefits include much finer control about what (and when) gets repli‐
231 cated from the master to other Tcl thread/interpreters.
232
234 thread, tpool, tsv
235
237 command tracing, introspection
238Tcl Threading 2.6 ttrace(n)