ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-Fork-Pool/Pool.pm
(Generate patch)

Comparing AnyEvent-Fork-Pool/Pool.pm (file contents):
Revision 1.13 by root, Sun Apr 28 14:27:31 2013 UTC vs.
Revision 1.16 by root, Tue Jun 7 04:45:20 2016 UTC

… …
3AnyEvent::Fork::Pool - simple process pool manager on top of AnyEvent::Fork 3AnyEvent::Fork::Pool - simple process pool manager on top of AnyEvent::Fork
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent; 7 use AnyEvent;
8 use AnyEvent::Fork;
8 use AnyEvent::Fork::Pool; 9 use AnyEvent::Fork::Pool;
9 # use AnyEvent::Fork is not needed
10 10
11 # all possible parameters shown, with default values 11 # all possible parameters shown, with default values
12 my $pool = AnyEvent::Fork 12 my $pool = AnyEvent::Fork
13 ->new 13 ->new
14 ->require ("MyWorker") 14 ->require ("MyWorker")
… …
46This module uses processes created via L<AnyEvent::Fork> (or 46This module uses processes created via L<AnyEvent::Fork> (or
47L<AnyEvent::Fork::Remote>) and the RPC protocol implement in 47L<AnyEvent::Fork::Remote>) and the RPC protocol implement in
48L<AnyEvent::Fork::RPC> to create a load-balanced pool of processes that 48L<AnyEvent::Fork::RPC> to create a load-balanced pool of processes that
49handles jobs. 49handles jobs.
50 50
51Understanding of L<AnyEvent::Fork> is helpful but not critical to be able 51Understanding L<AnyEvent::Fork> is helpful but not required to use this
52to use this module, but a thorough understanding of L<AnyEvent::Fork::RPC> 52module, but a thorough understanding of L<AnyEvent::Fork::RPC> is, as
53is, as it defines the actual API that needs to be implemented in the 53it defines the actual API that needs to be implemented in the worker
54worker processes. 54processes.
55 55
56=head1 PARENT USAGE 56=head1 PARENT USAGE
57 57
58To create a pool, you first have to create a L<AnyEvent::Fork> object - 58To create a pool, you first have to create a L<AnyEvent::Fork> object -
59this object becomes your template process. Whenever a new worker process 59this object becomes your template process. Whenever a new worker process
… …
86 86
87use Guard (); 87use Guard ();
88use Array::Heap (); 88use Array::Heap ();
89 89
90use AnyEvent; 90use AnyEvent;
91# explicit version on next line, as some cpan-testers test with the 0.1 version,
92# ignoring dependencies, and this line will at least give a clear indication of that.
93use AnyEvent::Fork 0.6; # we don't actually depend on it, this is for convenience
94use AnyEvent::Fork::RPC; 91use AnyEvent::Fork::RPC;
95 92
96# these are used for the first and last argument of events 93# these are used for the first and last argument of events
97# in the hope of not colliding. yes, I don't like it either, 94# in the hope of not colliding. yes, I don't like it either,
98# but didn't come up with an obviously better alternative. 95# but didn't come up with an obviously better alternative.
99my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P'; 96my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P';
100my $magic1 = '<~53rexz.U`!]X[A235^"fyEoiTF\T~oH1l/N6+Djep9b~bI9`\1x%B~vWO1q*'; 97my $magic1 = '<~53rexz.U`!]X[A235^"fyEoiTF\T~oH1l/N6+Djep9b~bI9`\1x%B~vWO1q*';
101 98
102our $VERSION = 1.1; 99our $VERSION = 1.2;
103 100
104=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...] 101=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...]
105 102
106The traditional way to call the pool creation function. But it is way 103The traditional way to call the pool creation function. But it is way
107cooler to call it in the following way: 104cooler to call it in the following way:
… …
400 397
401 last; 398 last;
402 } 399 }
403 } 400 }
404 } elsif ($shutdown) { 401 } elsif ($shutdown) {
405 @pool = (); 402 undef $_->[2]
403 for @pool;
404
406 undef $start_w; 405 undef $start_w;
407 undef $start_worker; # frees $destroy_guard reference 406 undef $start_worker; # frees $destroy_guard reference
408 407
409 $stop_worker->($pool[0]) 408 $stop_worker->($pool[0])
410 while $nidle; 409 while $nidle;
… …
449 448
450=item $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus] 449=item $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus]
451 450
452=item ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus] 451=item ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus]
453 452
454Tries to detect the number of CPUs (C<$cpus> often called cpu cores 453Tries to detect the number of CPUs (C<$cpus> often called CPU cores
455nowadays) and execution units (C<$eus>) which include e.g. extra 454nowadays) and execution units (C<$eus>) which include e.g. extra
456hyperthreaded units). When C<$cpus> cannot be determined reliably, 455hyperthreaded units). When C<$cpus> cannot be determined reliably,
457C<$default_cpus> is returned for both values, or C<1> if it is missing. 456C<$default_cpus> is returned for both values, or C<1> if it is missing.
458 457
459For normal CPU bound uses, it is wise to have as many worker processes 458For normal CPU bound uses, it is wise to have as many worker processes
… …
461hyperthreading is usually detrimental to performance, but in those rare 460hyperthreading is usually detrimental to performance, but in those rare
462cases where that really helps it might be beneficial to use more workers 461cases where that really helps it might be beneficial to use more workers
463(C<$eus>). 462(C<$eus>).
464 463
465Currently, F</proc/cpuinfo> is parsed on GNU/Linux systems for both 464Currently, F</proc/cpuinfo> is parsed on GNU/Linux systems for both
466C<$cpus> and C<$eu>, and on {Free,Net,Open}BSD, F<sysctl -n hw.ncpu> is 465C<$cpus> and C<$eus>, and on {Free,Net,Open}BSD, F<sysctl -n hw.ncpu> is
467used for C<$cpus>. 466used for C<$cpus>.
468 467
469Example: create a worker pool with as many workers as cpu cores, or C<2>, 468Example: create a worker pool with as many workers as CPU cores, or C<2>,
470if the actual number could not be determined. 469if the actual number could not be determined.
471 470
472 $fork->AnyEvent::Fork::Pool::run ("myworker::function", 471 $fork->AnyEvent::Fork::Pool::run ("myworker::function",
473 max => (scalar AnyEvent::Fork::Pool::ncpu 2), 472 max => (scalar AnyEvent::Fork::Pool::ncpu 2),
474 ); 473 );
… …
521 520
522=item AnyEvent::Fork::Pool::retire () 521=item AnyEvent::Fork::Pool::retire ()
523 522
524This function sends an event to the parent process to request retirement: 523This function sends an event to the parent process to request retirement:
525the worker is removed from the pool and no new jobs will be sent to it, 524the worker is removed from the pool and no new jobs will be sent to it,
526but it has to handle the jobs that are already queued. 525but it still has to handle the jobs that are already queued.
527 526
528The parentheses are part of the syntax: the function usually isn't defined 527The parentheses are part of the syntax: the function usually isn't defined
529when you compile your code (because that happens I<before> handing the 528when you compile your code (because that happens I<before> handing the
530template process over to C<AnyEvent::Fork::Pool::run>, so you need the 529template process over to C<AnyEvent::Fork::Pool::run>, so you need the
531empty parentheses to tell Perl that the function is indeed a function. 530empty parentheses to tell Perl that the function is indeed a function.
532 531
533Retiring a worker can be useful to gracefully shut it down when the worker 532Retiring a worker can be useful to gracefully shut it down when the worker
534deems this useful. For example, after executing a job, one could check 533deems this useful. For example, after executing a job, it could check the
535the process size or the number of jobs handled so far, and if either is 534process size or the number of jobs handled so far, and if either is too
536too high, the worker could ask to get retired, to avoid memory leaks to 535high, the worker could request to be retired, to avoid memory leaks to
537accumulate. 536accumulate.
538 537
539Example: retire a worker after it has handled roughly 100 requests. 538Example: retire a worker after it has handled roughly 100 requests. It
539doesn't matter whether you retire at the beginning or end of your request,
540as the worker will continue to handle some outstanding requests. Likewise,
541it's ok to call retire multiple times.
540 542
541 my $count = 0; 543 my $count = 0;
542 544
543 sub my::worker { 545 sub my::worker {
544 546
… …
550 552
551=back 553=back
552 554
553=head1 POOL PARAMETERS RECIPES 555=head1 POOL PARAMETERS RECIPES
554 556
555This section describes some recipes for pool paramaters. These are mostly 557This section describes some recipes for pool parameters. These are mostly
556meant for the synchronous RPC backend, as the asynchronous RPC backend 558meant for the synchronous RPC backend, as the asynchronous RPC backend
557changes the rules considerably, making workers themselves responsible for 559changes the rules considerably, making workers themselves responsible for
558their scheduling. 560their scheduling.
559 561
560=over 4 562=over 4
… …
589=item high throughput, I/O bound jobs - set load >= 2, max = 1, or very high 591=item high throughput, I/O bound jobs - set load >= 2, max = 1, or very high
590 592
591When your jobs are I/O bound, using more workers usually boils down to 593When your jobs are I/O bound, using more workers usually boils down to
592higher throughput, depending very much on your actual workload - sometimes 594higher throughput, depending very much on your actual workload - sometimes
593having only one worker is best, for example, when you read or write big 595having only one worker is best, for example, when you read or write big
594files at maixmum speed, as a second worker will increase seek times. 596files at maximum speed, as a second worker will increase seek times.
595 597
596=back 598=back
597 599
598=head1 EXCEPTIONS 600=head1 EXCEPTIONS
599 601
600The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptins will 602The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptions
601not be caught, and exceptions in both worker and in callbacks causes 603will not be caught, and exceptions in both worker and in callbacks causes
602undesirable or undefined behaviour. 604undesirable or undefined behaviour.
603 605
604=head1 SEE ALSO 606=head1 SEE ALSO
605 607
606L<AnyEvent::Fork>, to create the processes in the first place. 608L<AnyEvent::Fork>, to create the processes in the first place.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines