Ubuntu Manpage: tpool - Part of the Tcl threading extension implementing pools of worker threads.

NAME

       tpool - Part of the Tcl threading extension implementing pools of worker threads.

SYNOPSIS

       package require Tcl  8.4

       package require Thread  ?2.8?

       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

       This  package  creates  and manages pools of worker threads. It allows you to post jobs to
       worker threads and wait for their completion. The threadpool implementation is Tcl  event-
       loop  aware.  That  means that any time a caller is forced to wait for an event (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.

COMMANDS

tpool::create ?options?
This command creates new threadpool. It accepts several options as key-value pairs.
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 that a newly threadpool will have no worker threads
initialy. All worker threads will be started on demand by callers running
tpool::post command 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 new worker thread. If the number of
available worker threads is lower than the given number, 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
that the threadpool instance will allow 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.

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 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 normaly
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 empty list.

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 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 will not wait for one idle
worker. It will just place the job in the pool's job queue and return immediately.

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 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.

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 job still waiting to be processed. If the
job is already being executed by one of the worker threads, the job will not be
cancelled. 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.

tpool::preserve tpool
Each call to this command increments the reference counter of the threadpool tpool
by one (1). 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.

tpool::release tpool
Each call to this command decrements the reference counter of the threadpool tpool
by one (1).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. 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 Tcl
error.

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.
Number of workers is maintained to the count that was found prior suspending worker
activity. If you need to assure 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 to proceed. It will not create additional worker threads to handle
the work posted to the pool's work queue.

DISCUSSION

Threadpool is one of the most common threading paradigm when it comes to server
applications handling a large number of relatively small tasks. A very simplistic model
for building a server application would be to create a new thread each time a request
arrives and service the request in the new thread. One of the disadvantages of this
approach is that the overhead of creating a new thread for each request is significant; a
server that created a new thread for each request would spend more time and consume more
system resources in creating and destroying threads than in processing actual user
requests. In addition to the overhead of creating and destroying threads, active threads
consume system resources. Creating too many threads can cause the system to run out of
memory or trash due to excessive memory consumption.

A thread pool offers a solution to both the problem of thread life-cycle overhead and the
problem of resource trashing. By reusing threads for multiple tasks, the thread-creation
overhead is spread over many tasks. As a bonus, because the thread already exists when a
request arrives, the delay introduced by thread creation is eliminated. Thus, the request
can be serviced immediately. 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.

KEYWORDS