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