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:
|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 pools 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.|
|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.|
|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.|
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.
thread, tsv, ttrace
|Tcl Threading||TPOOL (n)||2.7|