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