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