thread(3tcl)

📦 version 3.0.6, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 thread — bestie, it's literally the Tcl threading extension 💖

okay so this is thread(3tcl), and it's the moment we stop pretending single-threaded is enough 🧚✨

✨ SYNOPSIS ✨

package require Tcl 9.0

package require thread ?3.0?

thread::create ?-joinable? ?-preserved? ?script?

thread::preserve ?id?

thread::release ?-wait? ?id?

thread::id

thread::errorproc ?procname?

thread::cancel ?-unwind? id ?result?

thread::unwind

thread::exit ?status?

thread::names

thread::exists id

thread::send ?-async? ?-head? id script ?varname?

thread::broadcast script

thread::wait

thread::eval ?-lock mutex? arg ?arg ...?

thread::join id

thread::configure id ?option? ?value? ?...?

thread::transfer id channel

thread::detach channel

thread::attach channel

thread::mutex

thread::mutex create ?-recursive?

thread::mutex destroy mutex

thread::mutex lock mutex

thread::mutex unlock mutex

thread::rwmutex

thread::rwmutex create

thread::rwmutex destroy mutex

thread::rwmutex rlock mutex

thread::rwmutex wlock mutex

thread::rwmutex unlock mutex

thread::cond

thread::cond create

thread::cond destroy cond

thread::cond notify cond

thread::cond wait cond mutex ?ms?

🌸 DESCRIPTION 🌸

so the thread extension makes threads, and those threads each contain a Tcl interpreter, and then you get to yeet scripts at them to be evaluated. that's the whole vibe. 💅

and ALSO — because why would we stop there — it hands you script-level access to the basic thread synchronization primitives: mutexes and condition variables. iconique.

👑 COMMANDS 👑

this section is the one that covers creating threads, destroying threads, and sending scripts to threads for evaluation. buckle up bestie, we're going in order 🫶

thread::create ?-joinable? ?-preserved? ?script?

okay so this command creates a thread, and that thread contains a Tcl interpreter. 🌈

the Tcl interpreter either evaluates the optional script, if you specified one, or it just sits there waiting in the event loop for scripts that arrive via the thread::send command. the result, if any, of the optional script is never returned to the caller — no cap, it just doesn't come back to you.

the result of thread::create is the ID of the thread. that's the opaque handle that identifies the newly created thread for every other command in the package. and the handle of the thread goes out of scope automatically when the thread is marked for exit (peep the thread::release command below).

if the optional script argument contains the thread::wait command, the thread will enter into the event loop. if that command is not found in the script, the thread will run the script to the end and then exit. in that case you can safely ignore the handle, because it refers to a thread that doesn't exist any more by the time the command returns. bye bestie 👋

  • -joinable — using this flag makes a joinable thread, i.e. one whose exit can be waited upon with the thread::join command.
⚠️ bestie listen: failure to join a thread created with the -joinable flag results in resource and memory leaks. not the vibe. don't do it. 😭

threads created by thread::create cannot be destroyed forcefully. consequently there is no corresponding thread destroy command — it just doesn't exist. a thread may only be released using thread::release, and if its internal reference count drops to zero, the thread is marked for exit. that kicks the thread out of the event loop servicing, and the thread continues to execute commands passed in the script argument, following the thread::wait command. if that was the last command in the script — as is usually the case — the thread will exit.

it is possible to create a situation in which it may be impossible to terminate the thread. for example, by putting some endless loop after the thread::wait, or by entering the event loop again by doing a vwait-type of command. in such cases, the thread may never exit. this is considered to be a bad practice and should be avoided if possible. this is best illustrated by the example below:

# You should never do ...
set tid [thread::create {
    package require Http
    thread::wait
    vwait forever ; # <-- this!
}]

the thread created in the above example will never be able to exit. after it has been released with the last matching thread::release call, the thread will jump out of the thread::wait and continue to execute commands following. it will enter the vwait command and wait endlessly for events. there is no way one can terminate such a thread, so you wouldn't want to do this! 💀

each newly created thread has its internal reference counter set to 0 (zero), i.e. it is unreserved. this counter gets incremented by a call to thread::preserve and decremented by a call to the thread::release command. these two commands implement a simple but effective thread reservation system and offer predictable and controllable thread termination capabilities. it is however possible to create initially preserved threads by using the -preserved flag of the thread::create command. threads created with this flag have the initial value of the reference counter of 1 (one), and are thus initially marked reserved. 🎀

thread::preserve ?id?

this one increments the thread reference counter. each call to this command increments the reference counter by one (1). the command returns the value of the reference counter after the increment.

if you call it with the optional thread id, the command preserves that given thread. otherwise the current thread gets preserved. either way, you're keeping it alive, bestie 🫶

with reference counting you can implement controlled access to a shared Tcl thread. by incrementing the reference counter, the caller signalizes that he/she wishes to use the thread for a longer period of time. by decrementing the counter, the caller signalizes that he/she has finished using the thread.

thread::release ?-wait? ?id?

this command decrements the thread reference counter. each call decrements the reference counter by one (1).

if you call it with the optional thread id, the command releases that given thread. otherwise, the current thread is released. the command returns the value of the reference counter after the decrement.

when the reference counter reaches zero (0), the target thread is marked for termination. 🪦

⚠️ you should not reference the thread after the thread::release command returns a zero or negative integer. the handle of the thread goes out of scope and should not be used any more. any following reference to the same thread handle will result in a Tcl error. no cap.
  • -wait — this optional flag instructs the caller thread to wait for the target thread to exit, if the effect of the command would result in termination of the target thread, i.e. if the return result would be zero (0). without the flag, the caller thread does not wait for the target thread to exit.
🚨 care must be taken when using -wait, since this may block the caller thread indefinitely. this option has been implemented for some special uses of the extension and is deprecated for regular use. regular users should create joinable threads by using the -joinable option of the thread::create command and the thread::join to wait for the thread to exit. periodt.

thread::id

this command returns the ID of the current thread. that's it, that's the whole command. iconic behaviour honestly ✨

thread::errorproc ?procname?

this command sets a handler for errors that occur in scripts sent asynchronously — using the -async flag of the thread::send command — to other threads.

if no handler is specified, the current handler is returned. the empty string resets the handler to the default (unspecified) value.

an uncaught error in a thread causes an error message to be sent to the standard error channel. this default reporting scheme can be changed by registering a procedure which is called to report the error. the procname is called in the interpreter that invoked the thread::errorproc command. the procname is called like this:

myerrorproc thread_id errorInfo

thread::cancel ?-unwind? id ?result?

💡 this command requires Tcl version 8.6 or higher.

cancels the script being evaluated in the thread given by the id parameter.

without the -unwind switch, the evaluation stack for the interpreter is unwound until an enclosing catch command is found, or there are no further invocations of the interpreter left on the call stack.

with the -unwind switch, the evaluation stack for the interpreter is unwound without regard to any intervening catch command until there are no further invocations of the interpreter left on the call stack. yeah. it does not care. 💀

if result is present, it will be used as the error message string; otherwise, a default error message string will be used.

thread::unwind

🚫 use of this command is deprecated in favour of the more advanced thread reservation system implemented with the thread::preserve and thread::release commands. support for the thread::unwind command will disappear in some future major release of the extension. iykyk.

this command stops a prior thread::wait command. execution of the script passed to the newly created thread will continue from the thread::wait command. if thread::wait was the last command in the script, the thread will exit.

the command returns an empty result but may trigger a Tcl error with the message target thread died in some situations. 😭

thread::exit ?status?

🚫 use of this command is deprecated in favour of the more advanced thread reservation system implemented with the thread::preserve and thread::release commands. support for the thread::exit command will disappear in some future major release of the extension.

...and it does this by forcing a thread that's stuck in thread::wait to dip out, no discussion. 💀 The exit status defaults to 666 and you can override it with the optional status argument. Now bestie, listen — the execution of thread::exit is guaranteed to leave your program memory in an inconsistent state, produce memory leaks, and otherwise mess with other subsystem(s) of the Tcl application in an unpredictable manner. It returns an empty result, but it may also trigger a Tcl error with the message "target thread died" in some situations. So yeah. It's giving last resort, not self-care. 🫠

thread::names ✨

Returns a list of thread IDs. Only for threads that have been created via thread::create. If your application creates other threads at the C level, they are not reported by this command. Sorry to those threads, they're not on the invite list. 🙈

thread::exists id 🌸

Returns true (1) if the thread given by the id parameter exists, false (0) otherwise. And again, this applies only to threads that have been created via thread::create. C-level threads? Not tracked, not acknowledged, not invited. 💅

thread::send ?-async? ?-head? id script ?varname? 🦋

This one passes a script to another thread and, optionally, waits for the result. If the -async flag is specified, the command does not wait for the result and it returns an empty string.

The target thread must enter its event loop in order to receive scripts sent via this command. This happens by default for threads created without a startup script. Threads can also enter the event loop explicitly by calling thread::wait or any other relevant Tcl/Tk command, like update, vwait, etc. 👑

Optional varname specifies the name of the variable to store the result of the script. Without the -async flag, the command returns the evaluation code, similarly to the standard Tcl catch command. If, however, the -async flag is specified, the command returns immediately and the caller can later vwait on ?varname? to get the result of the passed script:

set t1 [thread::create]
set t2 [thread::create]
thread::send -async $t1 "set a 1" result
thread::send -async $t2 "set b 2" result
for {set i 0} {$i < 2} {incr i} {
    vwait result
}

In the above example, two threads were fed work and both of them were instructed to signalize the same variable "result" in the calling thread. The caller entered the event loop twice to get both results. Note, however, that the order of the received results may vary, depending on the current system load, type of work done, etc, etc. So don't come for me about ordering, it's literally just vibes and CPU scheduling. 😭

Many threads can simultaneously send scripts to the target thread for execution. All of them are entered into the event queue of the target thread and executed on the FIFO basis, intermingled with optional other events pending in the event queue of the target thread. Using the optional ?-head? switch, scripts posted to the thread's event queue can be placed on the head, instead of the tail of the queue, thus being executed in the LIFO fashion. Queue jumping, but make it legal. 🔥

thread::broadcast script 📢

This command passes a script to all threads created by the package for execution. It does not wait for a response from any of the threads. Fire and forget, periodt.

The sending thread (the one executing the thread::broadcast command) does not send the script to itself. You can't text yourself, that's not a thing. 🙅

Each receiving thread is directed to place evaluation of the send script at the head of its event queue, stepping in front of any other events awaiting processing. Everyone cuts the line, it's iconic behavior actually. 💅

thread::wait 💤

This enters the event loop so a thread can receive messages from the thread::send command. This command should only be used within the script passed to thread::create. It should be the very last command in the script. If this is not the case, the exiting thread will continue executing the script lines past the thread::wait, which is usually not what you want and/or expect. 😬 So like, put it at the end, bestie.

set t1 [thread::create {
    #
    # Do some initialization work here
    #
    thread::wait ; # Enter the event loop
}]

thread::eval ?-lock mutex? arg ?arg ...? 🔐

This command concatenates the passed arguments and evaluates the resulting script under the mutex protection. If no mutex is specified by using the ?-lock mutex? optional argument, the internal static mutex is used.

thread::join id 🫶

This command waits for the thread with ID id to exit and then returns its exit code. Errors will be returned for threads which are not joinable or already waited upon by another thread. Upon the join, the handle of the thread has gone out of scope and should not be used any more. It's gone, girl, let it go. 🌈

thread::configure id ?option? ?value? ?...? ⚙️

This command configures various low-level aspects of the thread with ID id in a similar way as the standard Tcl command fconfigure configures some Tcl channel options. Options currently supported are: -eventmark and -unwindonerror.

  • -eventmark — when provided with a value greater than 0 (zero), that value is the maximum number of asynchronously posted scripts that may be pending for the thread. thread::send -async blocks until the number of pending scripts in the event loop drops below the -eventmark value. Basically a lil queue cap. 🧢
  • -unwindonerror — when provided with a value of true, an error result in a script causes the thread to unwind, making it unavailable to evaluate additional scripts. One bad script and she's done, respectfully. 💀

thread::transfer id channel 🚚

This moves the specified channel from the current thread and interpreter to the main interpreter of the thread with the given id. After the move the current interpreter has no access to the channel any more, but the main interpreter of the target thread will be able to use it from now on. The command waits until the other thread has incorporated the channel.

Because of this it is possible to deadlock the participating threads by commanding the other through a synchronous thread::send to transfer a channel to us. This easily extends into longer loops of threads waiting for each other. 🚩

Other restrictions: the channel in question must not be shared among multiple interpreters running in the sending thread. This automatically excludes the special channels for standard input, output and error.

Due to the internal Tcl core implementation and the restriction on transferring shared channels, one has to take extra measures when transferring socket channels created by accepting the connection out of the socket commands callback procedures:

socket -server _Accept 2200
proc _Accept {s ipaddr port} {
    after idle [list Accept $s $ipaddr $port]
}
proc Accept {s ipaddr port} {
    set tid [thread::create]
    thread::transfer $tid $s
}

thread::detach channel 🎈

This detaches the specified channel from the current thread and interpreter. After that, the current interpreter has no access to the channel any more. The channel is in the parked state until some other (or the same) thread attaches the channel again with thread::attach.

Restrictions: same as for transferring shared channels with the thread::transfer command. Same rules, same energy.

thread::attach channel 🧲

This attaches the previously detached channel in the current thread/interpreter. For already existing channels, the command does nothing, i.e. it is not an error to attach the same channel more than once. The first operation will actually perform the operation, while all subsequent operations will just do nothing.

Command throws an error if the channel cannot be found in the list of detached channels and/or in the current interpreter. No channel, no attach, sorry babe. 🙈

thread::mutex 🔒

Mutexes are the most common thread synchronization primitives. They are used to synchronize access from two or more threads to one or more shared resources. This command provides script-level access to exclusive and/or recursive mutexes.

Exclusive mutexes can be locked only once by one thread, while recursive mutexes can be locked many times by the same thread. For recursive mutexes, the number of lock and unlock operations must match, otherwise the mutex will never be released, which would lead to various deadlock situations. Matching your locks is not optional, it's the whole assignment. 😤

Care has to be taken when using mutexes in a multithreading program. Improper use of mutexes may lead to various deadlock situations, especially when using exclusive mutexes. Deadlocks are not cute. 🚫

The thread::mutex command supports the following subcommands and options:

thread::mutex create ?-recursive? 🎀

Creates the mutex and returns its opaque handle. This handle should be used for any future reference to the newly created mutex. If no optional ?-recursive? argument was specified, the command creates the exclusive mutex. With the ?-recursive? argument, the command creates a recursive mutex. Pick your fighter. 💖

thread::mutex destroy mutex 💥

Destroys the mutex. The mutex should be in an unlocked state before the destroy attempt. If the mutex is locked, the command will throw a Tcl error. Locked mutexes do not get destroyed, no cap.

thread::mutex lock mutex 🔐

Locks the mutex. Locking the exclusive mutex may throw a Tcl error on an attempt to lock the same mutex twice from the same thread. If your program logic forces you to lock the same mutex twice or more from the same thread (this may happen in recursive procedure invocations) you should consider using the recursive mutexes. Recursive girlies, this one's for you. ✨

thread::mutex unlock mutex 🔓

Unlocks the mutex so some other thread may lock it again. An attempt to unlock an already unlocked mutex will throw a Tcl error. You can't double-unlock, bestie, that's not a thing. 😭

thread::rwmutex 📚

This command creates many-readers/single-writer mutexes. Reader/writer mutexes allow you to serialize access to a shared resource more optimally. In situations where a shared resource gets mostly read and seldom modified, you might gain some performance by using reader/writer mutexes instead of exclusive or recursive mutexes. Read-heavy workloads, this is your main character moment. 👑

ok so if you're reading the resource, the thread grabs a read lock on it. read locks are non-exclusive — meaning like, multiple threads can hold a read lock on the same resource at the same time, no waiting on each other, no drama, we love that for us 🫶. but if you wanna change the resource? bestie you need an exclusive write lock. and that lock straight up blocks <em>every</em> thread from getting a read-lock while the writer thread is out here modifying the resource. only once the write lock gets released can the resource be read-locked again. periodt. 💅

the thread::rwmutex command supports these subcommands and options, and yes we're going through all of them:

  • thread::rwmutex create — makes the reader/writer mutex and hands you back its opaque handle. keep that handle, you'll use it for literally any future reference to your shiny new mutex 🎀
  • thread::rwmutex destroy mutex — destroys the reader/writer mutex. but heads up: if the mutex is already locked, trying to destroy it will throw a Tcl error 😭
  • thread::rwmutex rlock mutex — locks the mutex for reading. more than one thread can read-lock the same mutex at the same time, it's giving community 🤝
  • thread::rwmutex wlock mutex — locks the mutex for writing. only <em>one</em> thread may write-lock the same mutex at the same time. and if the same thread tries to write-lock the same mutex twice? Tcl error, no cap 💀
  • thread::rwmutex unlock mutex — unlocks the mutex so some other thread can lock it again. trying to unlock an already-unlocked mutex throws a Tcl error 🙈

✨ thread::cond ✨

okay this one's iconic. thread::cond gives you script-level access to condition variables. a condition variable creates a safe little environment where your program can test some condition, sleep on it when it's false, and get awakened when it might have become true 🦋.

a condition variable is always used in conjunction with an exclusive mutex. if you try to use any other type of mutex with the condition variable, a Tcl error gets thrown. that's the rule, bestie.

the command supports these subcommands and options:

  • thread::cond create — creates the condition variable and returns its opaque handle. use this handle for any future reference to your newly created condition variable 💖
  • thread::cond destroy cond — destroys the condition variable cond. but listen — you have to take extreme care that nobody is using (i.e. waiting on) the condition variable, otherwise unexpected errors may happen. like, do not do this while someone's mid-wait, fr fr 😭
  • thread::cond notify cond — wakes up <em>all</em> the threads waiting on the condition variable cond. rise and shine babes ☀️
  • thread::cond wait cond mutex ?ms? — suspends program execution until the condition variable cond has been signalled, or until the optional timer expires. the exclusive mutex <strong>must</strong> be locked by the calling thread on entrance to this command. if the mutex isn't locked, a Tcl error is thrown. while waiting on the cond, the command releases mutex. and before returning to the calling thread, it re-acquires the mutex again. unlocking the mutex and waiting on the condition variable cond is done atomically — chef's kiss 🤌

the ms option, if you give it, must be an integer specifying the time interval in milliseconds that the command waits to be signalled. otherwise the command waits on condition notify <em>forever</em>. forever-ever? forever-ever. 😳

in multithreading programs there are so many situations where a thread has to wait for some event to happen before it's allowed to proceed. this is usually accomplished by repeatedly testing a condition under mutex protection and waiting on the condition variable until the condition evaluates to true:

set mutex [thread::mutex create]
set cond  [thread::cond  create]

thread::mutex lock $mutex
while {<some_condition_is_true>} {
    thread::cond wait $cond $mutex
}
# Do some work under mutex protection
thread::mutex unlock $mutex

repeated testing of the condition is needed because the condition variable may get signalled <em>without</em> the condition actually being changed (spurious thread wake-ups, for example). so like, always loop, never trust a single wake-up 🫠

🌈 DISCUSSION 🌈

the fundamental threading model in Tcl is that there can be one or more Tcl interpreters per thread, but each Tcl interpreter should only ever be used by a <strong>single thread</strong> — the one that created it. main character energy, and only that one gets the mic 🎤

a "shared memory" abstraction is awkward to provide in Tcl because Tcl makes assumptions about variable and data ownership. so instead, this extension supports a simple form of threading where the main thread can manage several background, or "worker" threads. 💅

for example, an event-driven server can pass requests to worker threads, and then await responses from worker threads or new client requests. everything goes through the common Tcl event loop, so message passing between threads works naturally with event-driven I/O, vwait on variables, and so forth. the vibes are immaculate ✨

for the transfer of bulk information it is possible to move channels between the threads. slay.

and for advanced multithreading scripts, script-level access to two basic synchronization primitives — mutex and condition variables — is also supported. we love options 💖

👀 SEE ALSO 👀

http://www.tcl.tk/doc/howto/thread_model.html, tpool, tsv, ttrace

🔑 KEYWORDS 🔑

events, message passing, mutex, synchronization, thread

and that's the whole page, bestie!! 🎀 this was Tcl Threading version 3.0, the thread(3tcl) manual page — go forth and synchronize responsibly, ily, mwah 💋✨

📦 where this page comes from