ttrace(3tcl)

💖 ttrace — bestie edition 💖

okay so this is the manual page for ttrace, which lives in the Tcl Threading world (that's the 3tcl manual section btw). it's giving ✨*trace-based interpreter initialization*✨ and honestly? it's iconic. let's get into it 🫶

---

✨ NAME ✨

ttrace — trace-based interpreter initialization 💅

---

🌸 SYNOPSIS 🌸

package require Tcl 9.0

package require thread ?3.0?

ttrace::eval arg ?arg ...?

ttrace::enable

ttrace::disable

ttrace::cleanup

ttrace::update ?epoch?

ttrace::getscript

ttrace::atenable cmd arglist body

ttrace::atdisable cmd arglist body

ttrace::addtrace cmd arglist body

ttrace::addscript name body

ttrace::addresolver cmd arglist body

ttrace::addcleanup body

ttrace::addentry cmd var val

ttrace::getentry cmd var

ttrace::getentries cmd ?pattern?

ttrace::delentry cmd

ttrace::preload cmd

---

🦋 DESCRIPTION 🦋

so this package builds a whole framework for on-demand replication of the interpreter state across threads in a multithreading application. periodt. it does that by riding on the mechanics of Tcl command tracing plus the Tcl unknown command and its whole mechanism. iykyk 🔥

this package requires the Tcl threading extension, but ngl it can also be used stand-alone within the AOLserver, which is a scalable webserver from America Online. yes bestie, that AOL 💀

in a nutshell (and bestie you KNOW i love a nutshell), here's a short sample showing how ttrace gets down with the Tcl threading extension:

% package require ttrace
3.0.1

% 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

as you can see from all that 👆, the ttrace::eval and ttrace::update commands are the ones used to create a thread-wide definition of a simple Tcl procedure, and then replicate that definition out to all the threads — both the ones already existing and the ones created later. slay ✨

---

👑 USER COMMANDS 👑

this section is all about the user-level commands. those are the ones script writers get to use to control how the tracing framework executes. main character energy only 💅

• ttrace::eval arg ?arg ...? — this command concatenates the given arguments and evaluates the resulting Tcl command with the trace framework enabled. if the command execution went okay, it takes all the necessary steps to automatically propagate the trace epoch change to every thread 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 get automatically updated. and if the command execution resulted in a Tcl error, then no state propagation takes place at all. 🙈

this is literally the most important user-level command of the whole package, because it wraps most of the commands described below. that's what makes it so good — you only need to learn this one command to effectively use the package. the other commands, which we'll get to, are mostly there for the sake of completeness. 💖

• ttrace::enable — activates all the registered callbacks in the framework and starts a new trace epoch. the trace epoch encapsulates every change done to the interpreter while traces are activated.
• ttrace::disable — deactivates all the registered callbacks in the framework and closes the current trace epoch. bye bestie 👋
• ttrace::cleanup — used to clean up all the on-demand loaded resources in the interpreter. it effectively brings the Tcl interpreter back to its pristine state. a full reset, no cap.
• ttrace::update ?epoch? — used to refresh the state of the interpreter so it matches the optional trace epoch. if the optional epoch isn't given, it takes the most recent trace epoch. simple as.
• ttrace::getscript — returns a synthesized Tcl script which may be sourced in any interpreter. this script sets the stage for the Tcl unknown command so it can load traced resources from the in-memory database. normally this command gets automatically invoked by other higher-level commands like ttrace::eval and ttrace::update, so you don't gotta worry about it.

---

🎀 CALLBACK COMMANDS 🎀

a word upfront, bestie: the package already includes callbacks for tracing the following Tcl commands — proc, namespace, variable, load, and rename. plus, there's also a set of callbacks for tracing resources (object, classes) for XOTcl v1.3.8+, which is an OO-extension to Tcl. so you've got a solid base for solving most real-life needs, and it doubles as an example for anyone wanting to customize the package to cover their own specific needs. obsessed 🫶

below you'll find the commands for registering callbacks in the framework and for writing callback scripts. these callbacks get invoked by the framework in order to gather interpreter state changes, build the in-memory database, do custom cleanups, and handle various other tasks. let's go ⭐

• ttrace::atenable cmd arglist body — registers a Tcl callback to be activated at ttrace::enable. registered callbacks get activated on a FIFO basis. the callback definition includes the name of the callback, cmd, a list of callback arguments, arglist, and the body of the callback. effectively this actually resembles the call interface of the standard Tcl proc command.
• ttrace::atdisable cmd arglist body — registers a Tcl callback to be activated at ttrace::disable. registered callbacks get activated on a FIFO basis. the callback definition includes the name of the callback, cmd, a list of callback arguments, arglist, and the body of the callback. effectively this actually resembles the call interface of the standard Tcl proc command.
• ttrace::addtrace cmd arglist body — registers a Tcl callback to be activated for tracing the Tcl cmd command. the callback definition includes the name of the Tcl command to trace, cmd, a list of callback arguments, arglist, and the body of the callback. effectively this actually resembles the call interface of the standard Tcl proc command.
• ttrace::addscript name body — registers a Tcl callback to be activated for building a Tcl script that gets passed to other interpreters. this script is used to set the stage for the Tcl unknown command. registered callbacks get activated on a FIFO basis. the callback definition includes the name of the callback, name, and the body of the callback.
• ttrace::addresolver cmd arglist body — registers a Tcl callback to be activated by the overloaded Tcl unknown command. registered callbacks get activated on a FIFO basis. this callback is used to resolve the resource and load the resource in the current interpreter.
• ttrace::addcleanup body — registers a Tcl callback to be activated by the trace::cleanup. registered callbacks get activated on a FIFO basis.
• ttrace::addentry cmd var val — adds one entry to the named in-memory database.
• ttrace::getentry cmd var — returns the value of the entry from the named in-memory database.
• ttrace::getentries cmd ?pattern? — returns the names of all entries from the named in-memory database.
• ttrace::delentry cmd — deletes an entry from the named in-memory database. gone, girl 💅
• ttrace::preload cmd — registers the Tcl command to be loaded in the interpreter. commands registered this way will always be part of the interpreter, and won't be on-demand loaded by the Tcl unknown command.

---

💀 DISCUSSION 💀

okay so the common introspective state-replication approaches out there use a custom Tcl script to introspect the running interpreter and then synthesize another Tcl script to replicate that state in some other interpreter. this package? nope. it uses Tcl command traces instead. iconic behavior.

command traces get registered on selected Tcl commands, like proc, namespace, load, and other standard (and/or user-defined) Tcl commands. when activated, those traces build an in-memory database of created resources. that database is then used as a resource repository for the (overloaded) Tcl unknown command, which creates the requested resource in the interpreter on demand. this way, users can update just one interpreter (the master) in one thread, and replicate that interpreter state (or part of it) out to the other threads/interpreters in the process. so clean ✨

the immediate benefit of this approach is a much smaller memory footprint for the application and much faster thread creation. because instead of actually loading all the necessary procedures (and other resources) in every single thread at thread initialization time, it defers all that to the moment the resource is actually referenced — which means significant improvements in both memory consumption and thread initialization time. some tests have shown that the memory footprint of a multithreading Tcl application went down more than three times, and thread startup time was reduced by about 50 times. no cap. but bestie — note that your mileage may vary. 🙈 other benefits include much finer control over what (and when) stuff gets replicated from the master to the other Tcl threads/interpreters.

---

🌈 SEE ALSO 🌈

thread, tpool, tsv

---

⭐ KEYWORDS ⭐

command tracing, introspection

---

and that's the whole thing, bestie! 💖 this page came to you from Tcl Threading, version 3.0, and it's the ttrace(3tcl) manual — go forth and replicate your interpreter state across all your threads, you absolute queen 👑✨🦋