blib/lib/POE/Component/Pool/Thread.pm

filter: Statementstmt 83.3% 10 / 12 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 87.5% 14 / 16 CC 1 SCAR 0.7
CC
1
Cov
83%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
↑ Summary
1 package POE::Component::Pool::Thread;
2 # -----------------------------------------------------------------------------
3 # "THE BEER-WARE LICENSE" (Revision 43) borrowed from FreeBSD's jail.c:
4 # <tag@cpan.org> wrote this file. As long as you retain this notice you
5 # can do whatever you want with this stuff. If we meet some day, and you think
6 # this stuff is worth it, you can buy me a beer in return. Scott S. McCoy
7 # -----------------------------------------------------------------------------
8  
9 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 3 ▶use warnings FATAL => "all";
Subroutine BEGIN: called CC=1 SCAR=0.0
11 3 ▶ no warnings 'numeric'; # grep int hack
Subroutine BEGIN: called CC=1 SCAR=0.0
12 0 ▶use threads;
Subroutine BEGIN: called CC=1 SCAR=2.6
13 use threads::shared;
14 use Thread::Semaphore;
15 use Thread::Queue;
16 use IO::Handle;
17 use POE qw( Pipe::OneWay Filter::Line Wheel::ReadWrite );
18 use Fcntl;
19  
20 # Circumvent warnings...
21 BEGIN { run POE::Kernel }
22  
23 *VERSION = \0.015;
24  
25 use constant DEBUG => 0;
26  
27 sub new {
28 die __PACKAGE__, "->new() requires a balanced list" unless @_ % 2;
29  
30 my ($type, %opt) = @_;
31
32 $opt{inline_states} ||= {};
33 $opt{StartThreads} ||= 0;
34 $opt{MinFree} ||= 2;
35 $opt{MaxFree} ||= 10;
36  
37 POE::Session->create
38 ( inline_states => {
39 %{ $opt{inline_states} },
40  
41 _start => sub {
42 my ($kernel, $heap) = @_[ KERNEL, HEAP ];
43  
44 $kernel->alias_set($opt{Name}) if $opt{Name};
45  
46 $heap->{queue} = [];
47  
48 my ($pipe_in, $pipe_out) = POE::Pipe::OneWay->new;
49 $heap->{pipe_out} = $pipe_out;
50  
51 die "Unable to create pipe"
52 unless defined $pipe_in and defined $pipe_out;
53  
54 $heap->{wheel} = POE::Wheel::ReadWrite->new
55 ( Handle => $pipe_in,
56 InputEvent => "-thread_talkback",
57 ErrorEvent => "-thread_talkerror",
58 );
59  
60 for (1 .. $opt{StartThreads}) {
61 $kernel->call($_[SESSION], "-spawn_thread");
62 }
63  
64 goto $opt{inline_states}{_start} if $opt{inline_states}{_start};
65 },
66  
67 _stop => sub {
68 my ($kernel, $heap) = @_[ KERNEL, HEAP ];
69  
70 DEBUG && warn "Joining all threads";
71 for my $tid (keys %{ $heap->{thread} }) {
72 $heap->{thread}{$tid}{iqueue}->enqueue("last");
73 $heap->{thread}{$tid}{thread}->join;
74 }
75  
76 goto $opt{inline_states}{_stop} if $opt{inline_states}{_stop};
77 },
78  
79 _default => sub {
80 die "_default caught state: ", $_[ARG0];
81 },
82  
83 -thread_talkerror => sub { die $_[ARG0], $_[ARG2] },
84  
85 -thread_talkback => sub {
86 my ($kernel, $heap, $input) = @_[ KERNEL, HEAP, ARG0 ];
87 my ($tid, $command) = ($input =~ m/(\d+): (\w+)/);
88  
89 DEBUG and warn "Recieved: $input";
90  
91 # Depending upon the settings of perlvar's, its possible we may get
92 # some garbage through here.
93 if (defined $command) {
94 if ($command eq "cleanup") {
95 $kernel->yield(-execute_cleanup => $tid);
96 }
97 elsif ($command eq "collect") {
98 $kernel->yield(-collect_garbage => $tid);
99 }
100 }
101 },
102  
103 -collect_garbage => sub {
104 DEBUG && warn "GC Called, thread exited";
105
106 my ($kernel, $session, $heap, $tid) =
107 @_[ KERNEL, SESSION, HEAP, ARG0 ];
108  
109 my $tdsc = delete $heap->{thread}{$tid} or return;
110  
111 $tdsc->{thread}->join;
112  
113 unless ($kernel->refcount_decrement($session->ID, "thread")) {
114 delete $heap->{wheel};
115 }
116  
117 delete $tdsc->{$_} for keys %$tdsc;
118 },
119  
120 -execute_cleanup => sub {
121 my ($kernel, $session, $heap, $tid) =
122 @_[ KERNEL, SESSION, HEAP, ARG0 ];
123  
124 DEBUG && warn "GC Called, thread finished task";
125  
126 my $thread = $heap->{thread};
127 my @free = grep ${ $_->{semaphore} }, values %$thread;
128  
129 my $queue = $heap->{queue};
130 my $rqueue = $heap->{thread}{$tid}{rqueue};
131 my $iqueue = $heap->{thread}{$tid}{iqueue};
132  
133 if ($rqueue->pending) {
134 if ($opt{CallBack}) {
135 DEBUG && warn "Dispatching CallBack";
136 $opt{CallBack}->( @_[0..ARG0-1], @{$rqueue->dequeue} );
137 }
138 }
139  
140 if (@$queue) {
141 my $args = &share([]);
142 push @$args, @{ shift @$queue };
143  
144 $iqueue->enqueue($args);
145 }
146 elsif (@free > $opt{MaxFree}) {
147 (shift @free)->{iqueue}->enqueue("last");
148 }
149 },
150  
151 -spawn_thread => sub {
152 my ($kernel, $session, $heap) = @_[ KERNEL, SESSION, HEAP ];
153
154 return if $opt{MaxThreads} == scalar keys %{ $heap->{thread} };
155 DEBUG && warn "Spawning a new thread";
156  
157 my $semaphore = Thread::Semaphore->new;
158 my $iqueue = Thread::Queue->new;
159 my $rqueue = Thread::Queue->new;
160 my $pipe_out = $heap->{pipe_out};
161 my $queue = $heap->{queue};
162  
163 my $thread = threads->create
164 ( \&thread_entry_point,
165 $semaphore,
166 $iqueue,
167 $rqueue,
168 fileno($pipe_out),
169 $opt{EntryPoint} );
170  
171 $kernel->refcount_increment($session->ID, "thread");
172  
173 $heap->{thread}{$thread->tid} = {
174 semaphore => $semaphore,
175 iqueue => $iqueue,
176 rqueue => $rqueue,
177 thread => $thread,
178 lifespan => 0, # Not currently used
179 };
180  
181 if (@$queue) {
182 my $args = &share([]);
183 push @$args, @{ shift @$queue };
184  
185 $iqueue->enqueue($args);
186 }
187 },
188  
189 run => sub {
190 my ($kernel, $heap, @arg) = @_[ KERNEL, HEAP, ARG0 .. $#_ ];
191  
192 DEBUG && warn "Assigned a task";
193  
194 my $thread = $heap->{thread};
195 my @free = grep ${ $_->{semaphore} }, values %$thread;
196  
197 if (@free) {
198 my $tdsc = shift @free;
199  
200 # Trickery so we can pass this through Thread::Queue;
201 my $sharg = &share([]);
202  
203 # Just to be polite...
204 lock $sharg;
205 push @$sharg, @arg;
206  
207 DEBUG and warn "Enqueueing on ", $tdsc->{thread}->tid;
208  
209 $tdsc->{iqueue}->enqueue($sharg);
210 }
211 else {
212 push @{ $heap->{queue} }, [ @arg ];
213 }
214  
215 if (@free < $opt{MinFree}) {
216 unless (scalar(keys %$thread) >= $opt{MaxThreads}) {
217 $kernel->yield("-spawn_thread");
218 }
219 }
220 },
221  
222 shutdown => sub {
223 my ($kernel, $heap) = @_[ KERNEL, HEAP ];
224  
225 $heap->{shutdown} = 1;
226 $kernel->alias_remove($opt{Name});
227  
228 for my $thread (values %{ $heap->{thread} }) {
229 $thread->{iqueue}->enqueue("last");
230 }
231 },
232 },
233 );
234 }
235  
236 sub thread_entry_point {
237 my ($semaphore, $iqueue, $rqueue, $pipe_fd, $task) = @_;
238  
239 my $pipe = IO::Handle->new_from_fd($pipe_fd, "a") or die $!;
240  
241 # XXX Hack
242 my $code = $task;
243  
244 # Just incase
245 local $\ = "\n";
246  
247 while (my $action = $iqueue->dequeue) {
248 DEBUG and warn threads->self->tid, ": recieved action";
249 $semaphore->down;
250  
251 # lock $action;
252  
253 unless (ref $action) {
254 if ($action eq "last") {
255 $$semaphore = -1;
256 last;
257 }
258 }
259  
260 else {
261 my $arg = $action;
262 # lock $arg;
263  
264 # Just incase...
265 my $result = &share([]);
266 push @$result, $code->(@$arg);
267  
268 DEBUG and warn threads->self->tid, ": Enqueuing result: @$result";
269 $rqueue->enqueue($result);
270 }
271  
272 DEBUG and warn threads->self->tid, ": Requesting cleanup";
273  
274 $pipe->print( threads->self->tid, ": cleanup" );
275 $pipe->flush;
276  
277 $semaphore->up;
278 }
279  
280 $pipe->print( threads->self->tid, ": collect" );
281 $pipe->flush;
282 DEBUG and warn threads->self->tid, ": Requesting Destruction";
283 }
284  
285 1;
286  
287 =head1 NAME
288  
289 POE::Component::Pool::Thread - A POE Managed Boss/Worker threadpool.
290  
291 =head1 SYNOPSIS
292  
293 use POE qw( Component::Pool::Thread );
294
295 POE::Component::Pool::Thread->new
296 ( MinFree => 2,
297 MaxFree => 5,
298 MaxThreads => 15,
299 StartThrneads => 5,
300 Name => "ThreadPool",
301 EntryPoint => \&thread_entry_point,
302 CallBack => \&result_handler,
303 inline_states => {
304 _start => sub {
305 my ($kernel, $heap) = @_[ KERNEL, HEAP ];
306  
307 # We are inside the component session
308 $kernel->yield(run => @arguements);
309  
310 $kernel->post(ThreadPool => run => @arguements);
311 },
312 }
313 );
314  
315 sub thread_entry_point {
316 my (@arguements) = @_;
317  
318 return 1;
319 }
320  
321 sub result_handler {
322 my ($kernel, $result) = @_[ KERNEL, ARG0 ];
323  
324 $result == 1;
325 }
326  
327 =head1 DESCRIPTION
328  
329 This is an expand-on-demand thread pool managed through a POE session in a
330 manner that does not interfer with cooperative multitasking. A single pipe is
331 created, each thread communicates its state to the main process through this
332 pipe. No serialization occurs (these are threads, not child processes), so
333 execution is very fast.
334  
335 =head1 RATIONALE
336  
337 Cooperative Co-routine type programming isn't always available. Some third
338 party software (dependant libraries and/or modules) and particular tasks block
339 processing weither you like it or not.
340  
341 Creation of threads is alot of overhead, infact quite a bit more overhead under
342 the current implementation of ithreads than fork is. Allocating these
343 resources before you need them is an obvious solution to this problem, if you
344 create the threads and re-use them, they're around when you need them without
345 the horrendously slow threads->create() method.
346  
347 Communicating the results of a threads processing requires allowing it to exit.
348 This means you will require the overhead of threads->create() next time you
349 need to accomplish this task. With a thread pool designed in this fasion, the
350 main thread itself has its own process loop. The result of each iteration is
351 passed through a thread safe queue, allowing you to collect the results of a
352 threads execution without the thread exiting.
353  
354 =head1 CONSTRUCTOR
355  
356 =over 4
357  
358 =item new MANY THINGS
359  
360 The new constructor is the only package method available with this package. It
361 creates a POE thread pool session which you describe in the following
362 arguements.
363  
364 =over 4
365  
366 =item EntryPoint CODE
367  
368 This arguement describes the entry point of the thread and is required. In the
369 actual implementation, this is not actually an entry point. This is instead a
370 coderef the thread will call repeatedly. The arguements of this subroutine
371 will be the arguements recieved by the controlling session. In order to pass
372 references as arguements, each reference must be shared (L<threads::shared>).
373 Filehandles and blessed references cannot be shared. You will have to
374 translate them yourself. With file handles, you can pass simply the file
375 descriptor and reopen it in the child thread. With blessed references, you can
376 pass the datastructure only, and rebless the reference in the thread.
377  
378 =item CallBack CODE
379  
380 This arguement descirbes the result handler, which is where the captured
381 results of a threads last execution are sent. As with EntryPoint subroutine
382 arguements, any data structures you wish to pass through return results must be
383 explicitly shared (L<threads::shared>).
384  
385 =item Name ALIAS
386  
387 This arguement descirbes the default alias your threadpool session is given.
388  
389 =item StartThreads INTEGER
390  
391 This arguement describes the number of threads the component will create during
392 its "_start" state, or when the POE Session is being started. This should be a
393 number greater than MinFree and less than or equal to MaxFree.
394  
395 =item MaxThreads INTEGER
396  
397 This arguement descirbes the maximum number of threads this component will
398 create for this task. If the component is assigned more tasks than threads, it
399 will place the remaining tasks in an internal FIFO queue and assign them
400 threads as they complete their tasks.
401  
402 =item MinFree INTEGER
403  
404 This arguement sets the minimum number of free threads to maintain. When the
405 component is assigned a new task, if there are less than this number of threads
406 available, it will yield a request to create a new thread at the components
407 convience.
408  
409 =item MaxFree INTEGER
410  
411 This arguement provides the maximum number of free threads to maintain. Upon
412 completion of a task, this value is checked. If there are more free threads
413 than this value available, the oldest thread is asked to shut down.
414  
415 =back
416  
417 =back
418  
419 =head1 INLINE STATES
420  
421 =over 4
422  
423 =item run LIST
424  
425 The run state assigns a task to one of the free threads in the pool, or appends
426 the task to the components internal FIFO if no threads are available and our
427 thread resources are exhausted.
428  
429 =item shutdown
430  
431 This state politely asks all threads to exit, deletes the wheel watching the
432 one way pipe threads are using to communicate, removes the session alias and
433 awaits a clean session shutdown.
434  
435 =back
436  
437 =head1 BUGS
438  
439 Oh I'm pretty sure of it. If you find some, let me know.
440  
441 =head1 THANKS
442  
443 Matt Cashner
444  
445 Rocco Caputo
446  
447 =head1 AUTHOR
448  
449 Scott McCoy (tag@cpan.org)
450  
451 =cut
↑ Summary