tpool(3tcl)

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

💖 tpool — the Tcl threading extension's worker-thread-pool era 💖

okay bestie, gather round, because this is the tpool page from the 3tcl manual section and it is genuinely iconic. this is where Tcl gets a whole lil pool of worker threads and you just toss jobs at them. no cap.

✨ NAME ✨

tpool — part of the Tcl threading extension, and it's the part that implements pools of worker threads. periodt.

🌸 SYNOPSIS 🌸

package require Tcl 9.0

package require thread ?3.0?

tpool::create ?options?

tpool::names

tpool::post ?-detached? ?-nowait? tpool script

tpool::wait tpool joblist ?varname?

tpool::cancel tpool joblist ?varname?

tpool::get tpool job

tpool::preserve tpool

tpool::release tpool

tpool::suspend tpool

tpool::resume tpool

🦋 DESCRIPTION 🦋

so this package creates and manages pools of worker threads. it lets you post jobs to worker threads and wait for their completion. that's the whole vibe. 🫶

and here's the part that's lowkey the main character: the threadpool implementation is Tcl event-loop aware. which means any time a caller is forced to wait for an event — a job being completed, or a worker thread becoming idle or initialized — the implementation will enter the event loop and allow for servicing of other pending file or timer (or any other supported) events. so you're never just stuck stuck. she multitasks. 💅

👑 COMMANDS 👑

🎀 tpool::create ?options?

this command creates a new threadpool. it accepts several options as key-value pairs, and those options are used to tune some threadpool parameters. the command returns the ID of the newly created threadpool. ✨

following options are supported:

  • -minworkers number — minimum number of worker threads needed for this threadpool instance. during threadpool creation, the implementation will create somany worker threads upfront and will keep at least number of them alive during the lifetime of the threadpool instance. default value of this parameter is 0 (zero), which means a newly created threadpool will have no worker threads initially. all worker threads will be started on demand by callers running tpool::post and posting jobs to the job queue. 🐣
  • -maxworkers number — maximum number of worker threads allowed for this threadpool instance. if a new job is pending and there are no idle worker threads available, the implementation will try to create a new worker thread. if the number of available worker threads is lower than the given number, the new worker thread will start. the caller will automatically enter the event loop and wait until the worker thread has initialized. if, however, the number of available worker threads is equal to the given number, the caller will enter the event loop and wait for the first worker thread to get idle, thus ready to run the job. default value of this parameter is 4 (four), which means the threadpool instance will allow a maximum of 4 worker threads running jobs or being idle waiting for new jobs to get posted to the job queue. 🔥
  • -idletime seconds — time in seconds an idle worker thread waits for the job to get posted to the job queue. if no job arrives during this interval and the time expires, the worker thread will check the number of currently available worker threads and, if the number is higher than the number set by the minthreads option, it will exit. if an exitscript has been defined, the exiting worker thread will first run the script and then exit. errors from the exit script, if any, are ignored.
heads up bestie: the idle worker thread is not servicing the event loop. if you, however, put the worker thread into the event loop, by evaluating the vwait or other related Tcl commands, the worker thread will not be in the idle state, hence the idle timer will not be taken into account. 😭

default value for this option is unspecified.

  • -initcmd script — sets a Tcl script used to initialize a new worker thread. this is usually used to load packages and commands in the worker, set default variables, create namespaces, and such. if the passed script runs into a Tcl error, the worker will not be created and the initiating command (either the tpool::create or tpool::post) will throw error. default value for this option is unspecified, hence the Tcl interpreter of the worker thread will contain just the initial set of Tcl commands. 🌱
  • -exitcmd script — sets a Tcl script run when the idle worker thread exits. this is normally used to cleanup the state of the worker thread, release reserved resources, cleanup memory and such. default value for this option is unspecified, thus no Tcl script will run on the worker thread exit. 🧹

🌈 tpool::names

this command returns a list of IDs of threadpools created with the tpool::create command. if no threadpools were found, the command will return an empty list. not a single one. empty. 💀 (but like, peacefully empty.)

💜 tpool::post ?-detached? ?-nowait? tpool script

this command sends a script to the target tpool threadpool for execution. the script will be executed in the first available idle worker thread. if there are no idle worker threads available, the command will create a new one, enter the event loop and service events until the newly created thread is initialized. if the current number of worker threads is equal to the maximum number of worker threads, as defined during the threadpool creation, the command will enter the event loop and service events while waiting for one of the worker threads to become idle.

if the optional ?-nowait? argument is given, the command just places the job in the pool's job queue without waiting for an idle worker or creating a new one, even if the pool would still have room for additional threads. she said "i'm not waiting around, i'm dropping it in the queue." 💅

the command returns the ID of the posted job. this ID is used for subsequent tpool::wait, tpool::get and tpool::cancel commands to wait for and retrieve the result of the posted script, or cancel the posted job respectively.

if the optional ?-detached? argument is specified, the command will post a detached job. a detached job can not be cancelled or waited upon and is not identified by the job ID. it's giving "i'm free, don't @ me." 🦋

if the threadpool tpool is not found in the list of active thread pools, the command will throw error. the error will also be triggered if the newly created worker thread fails to initialize. 😤

🍓 tpool::wait tpool joblist ?varname?

this command waits for one or many jobs, whose job IDs are given in the joblist, to get processed by the worker thread(s). if none of the specified jobs are ready, the command will enter the event loop, service events and wait for the first job to get ready. ⏳

the command returns the list of completed job IDs. if the optional variable varname is given, it will be set to the list of jobs in the joblist which are still pending. if the threadpool tpool is not found in the list of active thread pools, the command will throw error.

💅 tpool::cancel tpool joblist ?varname?

this command cancels the previously posted jobs given by the joblist to the pool tpool. job cancellation succeeds only for jobs still waiting to be processed. if the job is already being executed by one of the worker threads, the job will not be cancelled. sorry bestie, once she's in motion she's in motion. 😭

the command returns the list of cancelled job IDs. if the optional variable varname is given, it will be set to the list of jobs in the joblist which were not cancelled. if the threadpool tpool is not found in the list of active thread pools, the command will throw error.

🧚 tpool::get tpool job

this command retrieves the result of the previously posted job. only results of jobs waited upon with the tpool::wait command can be retrieved. if the execution of the script resulted in error, the command will throw the error and update the errorInfo and errorCode variables correspondingly. 🚨

if the pool tpool is not found in the list of threadpools, the command will throw error. if the job job is not ready for retrieval, because it is currently being executed by the worker thread, the command will throw error. ngl, patience is a virtue here.

⭐ tpool::preserve tpool

each call to this command increments the reference counter of the threadpool tpool by one (1). the command returns the value of the reference counter after the increment. by incrementing the reference counter, the caller signalizes that he/she wishes to use the resource for a longer period of time. it's giving "i'm claiming this, hold my spot." 🫶

💖 tpool::release tpool

each call to this command decrements the reference counter of the threadpool tpool by one (1). the command returns the value of the reference counter after the decrement. when the reference counter reaches zero (0), the threadpool tpool is marked for termination.

okay so this part is important and i need you to actually listen: you should not reference the threadpool after the tpool::release command returns zero. the tpool handle goes out of scope and should not be used any more. any following reference to the same threadpool handle will result in a Tcl error. fr fr. don't do it. 💀

🌸 tpool::suspend tpool

suspends processing work on this queue. all pool workers are paused but additional work can be added to the pool. note that adding the additional work will not increase the number of workers dynamically as the pool processing is suspended. the number of workers is maintained to the count that was found prior to suspending worker activity. if you need to assure a certain number of worker threads, use the minworkers option of the tpool::create command. 🛑

🎀 tpool::resume tpool

resume processing work on this queue. all paused (suspended) workers are free to get work from the pool. note that resuming pool operation will just let already created workers proceed. it will not create additional worker threads to handle the work posted to the pool's work queue. she's back, but she's working with the crew she already has. 💅✨

💬 DISCUSSION 💬

ok so bestie, listen — threadpool is literally the most common threading paradigm when it comes to server applications that handle a large number of relatively small tasks. it's giving main character energy for a reason. ✨

so picture this super simplistic model for building a server app: every single time a request shows up, you just create a new thread and service that request inside the new thread. cute, right? 🙈 wrong. one of the disadvantages is that the overhead of creating a new thread for each request is significant. like, a server that made a brand new thread for every single request would spend more time — and burn more system resources — creating and destroying threads than actually processing user requests. not the vibe. 💀

and it gets worse, bestie. on top of all that create-and-destroy overhead, active threads consume system resources. so creating too many threads can cause the system to run out of memory or thrash due to excessive memory consumption. it's giving chaos. 😭

now here's where the thread pool comes in and ate. 👑

a thread pool offers a solution to both problems:

  • the problem of thread life-cycle overhead
  • the problem of resource thrashing

by reusing threads for multiple tasks, the thread-creation overhead gets spread over many tasks instead of being paid fresh every time. slay.

and as a bonus — because the thread already exists when a request arrives, the delay introduced by thread creation is eliminated. so the request can be serviced immediately. no waiting, no loading screen, no nothing. periodt. 💅

furthermore, by properly tuning the number of threads in the thread pool, resource thrashing may also be eliminated — by forcing any request to wait until a thread is available to process it. she's patient, she's organized, she's iconic. 🎀

🌸 SEE ALSO 🌸

  • thread
  • tsv
  • ttrace

🦋 KEYWORDS 🦋

thread, threadpool

ok that's the whole page bestie, we made it 🫶 this one's from Tcl Threading, version 3.0, and it's the tpool(3tcl) manual page. go forth and thread pool responsibly, no cap. 💖✨🎀

📦 where this page comes from