1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin tpool n 2.6] 3[moddesc {Tcl Threading}] 4[titledesc { 5 Part of the Tcl threading extension implementing pools of worker threads. 6}] 7[require Tcl 8.4] 8[require Thread [opt 2.6]] 9 10[description] 11This package creates and manages pools of worker threads. It allows you 12to post jobs to worker threads and wait for their completion. The 13threadpool implementation is Tcl event-loop aware. That means that any 14time a caller is forced to wait for an event (job being completed or 15a worker thread becoming idle or initialized), the implementation will 16enter the event loop and allow for servicing of other pending file or 17timer (or any other supported) events. 18 19[section COMMANDS] 20 21[list_begin definitions] 22 23[call [cmd tpool::create] [opt options]] 24 25This command creates new threadpool. It accepts several options as 26key-value pairs. Options are used to tune some threadpool parameters. 27The command returns the ID of the newly created threadpool. 28[nl] 29Following options are supported: 30 31[list_begin definitions] 32 33[lst_item {-minworkers number}] 34Minimum number of worker threads needed for this threadpool instance. 35During threadpool creation, the implementation will create somany 36worker threads upfront and will keep at least number of them alive 37during the lifetime of the threadpool instance. 38Default value of this parameter is 0 (zero). which means that a newly 39threadpool will have no worker threads initialy. All worker threads 40will be started on demand by callers running [cmd tpool::post] command 41and posting jobs to the job queue. 42 43[lst_item {-maxworkers number}] 44Maximum number of worker threads allowed for this threadpool instance. 45If a new job is pending and there are no idle worker threads available, 46the implementation will try to create new worker thread. If the number 47of available worker threads is lower than the given number, 48new worker thread will start. The caller will automatically enter the 49event loop and wait until the worker thread has initialized. If. however, 50the number of available worker threads is equal to the given number, 51the caller will enter the event loop and wait for the first worker thread 52to get idle, thus ready to run the job. 53Default value of this parameter is 4 (four), which means that the 54threadpool instance will allow maximum of 4 worker threads running jobs 55or being idle waiting for new jobs to get posted to the job queue. 56 57 58[lst_item {-idletime seconds}] 59Time in seconds an idle worker thread waits for the job to get posted 60to the job queue. If no job arrives during this interval and the time 61expires, the worker thread will check the number of currently available 62worker threads and if the number is higher than the number set by the 63[option minthreads] option, it will exit. 64If an [option exitscript] has been defined, the exiting worker thread 65will first run the script and then exit. Errors from the exit script, 66if any, are ignored. 67[nl] 68The idle worker thread is not servicing the event loop. If you, however, 69put the worker thread into the event loop, by evaluating the 70[cmd vwait] or other related Tcl commands, the worker thread 71will not be in the idle state, hence the idle timer will not be 72taken into account. 73Default value for this option is unspecified, hence, the Tcl interpreter 74of the worker thread will contain just the initial set of Tcl commands. 75 76[lst_item {-initcmd script}] 77 78Sets a Tcl script used to initialize new worker thread. This is usually 79used to load packages and commands in the worker, set default variables, 80create namespaces, and such. If the passed script runs into a Tcl error, 81the worker will not be created and the initiating command (either the 82[cmd tpool::create] or [cmd tpool::post]) will throw error. 83Default value for this option is unspecified, hence, the Tcl interpreter of 84the worker thread will contain just the initial set of Tcl commands. 85 86[lst_item {-exitcmd script}] 87 88Sets a Tcl script run when the idle worker thread exits. This is normaly 89used to cleanup the state of the worker thread, release reserved resources, 90cleanup memory and such. 91Default value for this option is unspecified, thus no Tcl script will run 92on the worker thread exit. 93 94[list_end] 95 96[nl] 97 98[call [cmd tpool::names]] 99 100This command returns a list of IDs of threadpools created with the 101[cmd tpool::create] command. If no threadpools were found, the 102command will return empty list. 103 104[call [cmd tpool::post] [opt -detached] [opt -nowait] [arg tpool] [arg script]] 105 106This command sends a [arg script] to the target [arg tpool] threadpool 107for execution. The script will be executed in the first available idle 108worker thread. If there are no idle worker threads available, the command 109will create new one, enter the event loop and service events until the 110newly created thread is initialized. If the current number of worker 111threads is equal to the maximum number of worker threads, as defined 112during the threadpool creation, the command will enter the event loop and 113service events while waiting for one of the worker threads to become idle. 114If the optional [opt -nowait] argument is given, the command will not wait 115for one idle worker. It will just place the job in the pool's job queue 116and return immediately. 117[nl] 118The command returns the ID of the posted job. This ID is used for subsequent 119[cmd tpool::wait], [cmd tpool::get] and [cmd tpool::cancel] commands to wait 120for and retrieve result of the posted script, or cancel the posted job 121respectively. If the optional [opt -detached] argument is specified, the 122command will post a detached job. A detached job can not be cancelled or 123waited upon and is not identified by the job ID. 124[nl] 125If the threadpool [arg tpool] is not found in the list of active 126thread pools, the command will throw error. The error will also be triggered 127if the newly created worker thread fails to initialize. 128 129[call [cmd tpool::wait] [arg tpool] [arg joblist] [opt varname]] 130 131This command waits for one or many jobs, whose job IDs are given in the 132[arg joblist] to get processed by the worker thread(s). If none of the 133specified jobs are ready, the command will enter the event loop, service 134events and wait for the first job to get ready. 135[nl] 136The command returns the list of completed job IDs. If the optional variable 137[opt varname] is given, it will be set to the list of jobs in the 138[arg joblist] which are still pending. If the threadpool [arg tpool] 139is not found in the list of active thread pools, the command will throw error. 140 141[call [cmd tpool::cancel] [arg tpool] [arg joblist] [opt varname]] 142 143This command cancels the previously posted jobs given by the [arg joblist] 144to the pool [arg tpool]. Job cancellation succeeds only for job still 145waiting to be processed. If the job is already being executed by one of 146the worker threads, the job will not be cancelled. 147The command returns the list of cancelled job IDs. If the optional variable 148[opt varname] is given, it will be set to the list of jobs in the 149[arg joblist] which were not cancelled. If the threadpool [arg tpool] 150is not found in the list of active thread pools, the command will throw error. 151 152[call [cmd tpool::get] [arg tpool] [arg job]] 153 154This command retrieves the result of the previously posted [arg job]. 155Only results of jobs waited upon with the [cmd tpool::wait] command 156can be retrieved. If the execution of the script resulted in error, 157the command will throw the error and update the [var errorInfo] and 158[var errorCode] variables correspondingly. If the pool [arg tpool] 159is not found in the list of threadpools, the command will throw error. 160If the job [arg job] is not ready for retrieval, because it is currently 161being executed by the worker thread, the command will throw error. 162 163[call [cmd tpool::preserve] [arg tpool]] 164 165Each call to this command increments the reference counter of the 166threadpool [arg tpool] by one (1). Command returns the value of the 167reference counter after the increment. 168By incrementing the reference counter, the caller signalizes that 169he/she wishes to use the resource for a longer period of time. 170 171[call [cmd tpool::release] [arg tpool]] 172 173Each call to this command decrements the reference counter of the 174threadpool [arg tpool] by one (1).Command returns the value of the 175reference counter after the decrement. 176When the reference counter reaches zero (0), the threadpool [arg tpool] 177is marked for termination. You should not reference the threadpool 178after the [cmd tpool::release] command returns zero. The [arg tpool] 179handle goes out of scope and should not be used any more. Any following 180reference to the same threadpool handle will result in Tcl error. 181 182[call [cmd tpool::suspend] [arg tpool]] 183 184Suspends processing work on this queue. All pool workers are paused 185but additional work can be added to the pool. Note that adding the 186additional work will not increase the number of workers dynamically 187as the pool processing is suspended. Number of workers is maintained 188to the count that was found prior suspending worker activity. 189If you need to assure certain number of worker threads, use the 190[option minworkers] option of the [cmd tpool::create] command. 191 192[call [cmd tpool::resume] [arg tpool]] 193 194Resume processing work on this queue. All paused (suspended) 195workers are free to get work from the pool. Note that resuming pool 196operation will just let already created workers to proceed. 197It will not create additional worker threads to handle the work 198posted to the pool's work queue. 199 200[list_end] 201 202 203[section DISCUSSION] 204 205Threadpool is one of the most common threading paradigm when it comes 206to server applications handling a large number of relatively small tasks. 207A very simplistic model for building a server application would be to 208create a new thread each time a request arrives and service the request 209in the new thread. One of the disadvantages of this approach is that 210the overhead of creating a new thread for each request is significant; 211a server that created a new thread for each request would spend more time 212and consume more system resources in creating and destroying threads than 213in processing actual user requests. In addition to the overhead of 214creating and destroying threads, active threads consume system resources. 215Creating too many threads can cause the system to run out of memory or 216trash due to excessive memory consumption. 217[para] 218A thread pool offers a solution to both the problem of thread life-cycle 219overhead and the problem of resource trashing. By reusing threads for 220multiple tasks, the thread-creation overhead is spread over many tasks. 221As a bonus, because the thread already exists when a request arrives, 222the delay introduced by thread creation is eliminated. Thus, the request 223can be serviced immediately. Furthermore, by properly tuning the number 224of threads in the thread pool, resource thrashing may also be eliminated 225by forcing any request to wait until a thread is available to process it. 226 227[see_also tsv ttrace thread] 228 229[keywords thread threadpool] 230 231[manpage_end] 232