Manual Pages for UNIX Darwin command on man tpool

tpool(n) tpool(n)

NAME

tpool - Part of the Tcl threading extension implementing pools of

worker threads.

SYNOPSIS

package require TTccll 88..33 package require TThhrreeaadd ??22..66?? ttppooooll::::ccrreeaattee ?options? ttppooooll::::nnaammeess

ttppooooll::::ppoosstt ?-detached? ?-nowait? tpool script

ttppooooll::::wwaaiitt tpool joblist ?varname?

ttppooooll::::ccaanncceell tpool joblist ?varname?

ttppooooll::::ggeett tpool job

ttppooooll::::pprreesseerrvvee tpool

ttppooooll::::rreelleeaassee 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. CCOOMMMMAANNDDSS ttppooooll::::ccrreeaattee ?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 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 ttppooooll::::ppoosstt command and posting jobs to the job queue.

-maxthreads number

Maximum number of 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 ini-

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

pool instance will allow maximum of 4 worker threads run-

ning 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 mmiinntthhrreeaaddss option, it will exit. If an eexxiittssccrriipptt 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 vvwwaaiitt or other related Tcl com-

mands, 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 ttppooooll::::ccrreeaattee or ttppooooll::::ppoosstt) will throw error. Default value for this option is unspecified,

hence, the Tcl interpreter of the worker thread will con-

tain 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. ttppooooll::::nnaammeess This command returns a list of IDs of threadpools created with the ttppooooll::::ccrreeaattee command. If no threadpools were found, the command will return empty list.

ttppooooll::::ppoosstt ?-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, 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 cre-

ation, 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 ttppooooll::::wwaaiitt, ttppooooll::::ggeett and ttppooooll::::ccaanncceell com-

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

ttppooooll::::wwaaiitt 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 thread-

pool tpool is not found in the list of active thread pools, the

command will throw error.

ttppooooll::::ccaanncceell 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 can-

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

ttppooooll::::ggeett tpool job

This command retrieves the result of the previously posted job. Only results of jobs waited upon with the ttppooooll::::wwaaiitt command can be retrieved. If the execution of the script resulted in error, the command will throw the error and update the eerrrroorrIInnffoo

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

ttppooooll::::pprreesseerrvvee 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.

ttppooooll::::rreelleeaassee 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

ttppooooll::::rreelleeaassee command returns zero. The tpool handle goes out

of scope and should not be used any more. Any following refer-

ence to the same threadpool handle will result in Tcl error. DDIISSCCUUSSSSIIOONN 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 signifi-

cant; 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 tun-

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