NAME¶
tpool - Part of the Tcl threading extension implementing pools of worker
threads.
SYNOPSIS¶
package require
Tcl 8.4
package require
Thread ?2.6?
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
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, hence, the Tcl interpreter of the worker
thread will contain just the initial set of Tcl commands.
- -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.
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.
SEE ALSO¶
thread, tsv, ttrace
KEYWORDS¶
thread, threadpool