tpool(n) tpool(n)
____________________________________________________________________________________________________________
NAME
tpool - Part of the Tcl threading extension implementing pools of worker threads.
SYNOPSIS
package require Tcl 8.3
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:
-minthreads number
Minimum number of threads needed for this threadpool instance. During threadpool cre-ation, creation,
ation, 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 run-ning running
ning tpool::post command and posting jobs to the job queue.
-maxthreads number
Maximum number of threads allowed for this threadpool instance. If a new job is pend-ing pending
ing and there are no idle worker threads available, the implementation will try to cre-ate create
ate 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 avail-able, available,
able, 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 ini-tialize. initialize.
tialize.
tpool::wait tpool joblist ?varname?
This command waits for one or many jobs, whose job IDs are given in the joblist to get pro-cessed processed
cessed 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 cor-respondingly. correspondingly.
respondingly. 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 exe-cuted executed
cuted 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 refer-ence reference
ence 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 intro-duced introduced
duced 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 elimi-nated eliminated
nated by forcing any request to wait until a thread is available to process it.
SEE ALSO
thread, tsv, ttrace
KEYWORDS
thread, threadpool
Tcl Threading 2.6 tpool(n)
|