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