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.8 by root, Sun Apr 21 12:28:34 2013 UTC vs.
Revision 1.17 by root, Thu Oct 27 07:27:56 2022 UTC

1=head1 NAME 1=head1 NAME
2 2
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
5THE API IS NOT FINISHED, CONSIDER THIS AN ALPHA RELEASE
6
7=head1 SYNOPSIS 5=head1 SYNOPSIS
8 6
9 use AnyEvent; 7 use AnyEvent;
8 use AnyEvent::Fork;
10 use AnyEvent::Fork::Pool; 9 use AnyEvent::Fork::Pool;
11 # use AnyEvent::Fork is not needed
12 10
13 # all possible parameters shown, with default values 11 # all possible parameters shown, with default values
14 my $pool = AnyEvent::Fork 12 my $pool = AnyEvent::Fork
15 ->new 13 ->new
16 ->require ("MyWorker") 14 ->require ("MyWorker")
… …
43 41
44 $finish->recv; 42 $finish->recv;
45 43
46=head1 DESCRIPTION 44=head1 DESCRIPTION
47 45
48This module uses processes created via L<AnyEvent::Fork> and the RPC 46This module uses processes created via L<AnyEvent::Fork> (or
49protocol implement in L<AnyEvent::Fork::RPC> to create a load-balanced 47L<AnyEvent::Fork::Remote>) and the RPC protocol implement in
50pool of processes that handles jobs. 48L<AnyEvent::Fork::RPC> to create a load-balanced pool of processes that
49handles jobs.
51 50
52Understanding of L<AnyEvent::Fork> is helpful but not critical to be able 51Understanding L<AnyEvent::Fork> is helpful but not required to use this
53to use this module, but a thorough understanding of L<AnyEvent::Fork::RPC> 52module, but a thorough understanding of L<AnyEvent::Fork::RPC> is, as
54is, 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
55worker processes. 54processes.
56
57=head1 EXAMPLES
58 55
59=head1 PARENT USAGE 56=head1 PARENT USAGE
60 57
61To 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 -
62this object becomes your template process. Whenever a new worker process 59this object becomes your template process. Whenever a new worker process
… …
89 86
90use Guard (); 87use Guard ();
91use Array::Heap (); 88use Array::Heap ();
92 89
93use AnyEvent; 90use AnyEvent;
94use AnyEvent::Fork; # we don't actually depend on it, this is for convenience
95use AnyEvent::Fork::RPC; 91use AnyEvent::Fork::RPC;
96 92
97# these are used for the first and last argument of events 93# these are used for the first and last argument of events
98# 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,
99# but didn't come up with an obviously better alternative. 95# but didn't come up with an obviously better alternative.
100my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P'; 96my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P';
101my $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*';
102 98
103our $VERSION = 0.1; 99our $VERSION = 1.3;
104 100
105=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...] 101=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...]
106 102
107The 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
108cooler to call it in the following way: 104cooler to call it in the following way:
… …
401 397
402 last; 398 last;
403 } 399 }
404 } 400 }
405 } elsif ($shutdown) { 401 } elsif ($shutdown) {
406 @pool = (); 402 undef $_->[2]
403 for @pool;
404
407 undef $start_w; 405 undef $start_w;
408 undef $start_worker; # frees $destroy_guard reference 406 undef $start_worker; # frees $destroy_guard reference
409 407
410 $stop_worker->($pool[0]) 408 $stop_worker->($pool[0])
411 while $nidle; 409 while $nidle;
… …
446to this function are effectively read-only - modifying them after the call 444to this function are effectively read-only - modifying them after the call
447and before the callback is invoked causes undefined behaviour. 445and before the callback is invoked causes undefined behaviour.
448 446
449=cut 447=cut
450 448
449=item $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus]
450
451=item ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus]
452
453Tries to detect the number of CPUs (C<$cpus> often called CPU cores
454nowadays) and execution units (C<$eus>) which include e.g. extra
455hyperthreaded units). When C<$cpus> cannot be determined reliably,
456C<$default_cpus> is returned for both values, or C<1> if it is missing.
457
458For normal CPU bound uses, it is wise to have as many worker processes
459as CPUs in the system (C<$cpus>), if nothing else uses the CPU. Using
460hyperthreading is usually detrimental to performance, but in those rare
461cases where that really helps it might be beneficial to use more workers
462(C<$eus>).
463
464Currently, F</proc/cpuinfo> is parsed on GNU/Linux systems for both
465C<$cpus> and C<$eus>, and on {Free,Net,Open}BSD, F<sysctl -n hw.ncpu> is
466used for C<$cpus>.
467
468Example: create a worker pool with as many workers as CPU cores, or C<2>,
469if the actual number could not be determined.
470
471 $fork->AnyEvent::Fork::Pool::run ("myworker::function",
472 max => (scalar AnyEvent::Fork::Pool::ncpu 2),
473 );
474
475=cut
476
477BEGIN {
478 if ($^O eq "linux") {
479 *ncpu = sub(;$) {
480 my ($cpus, $eus);
481
482 if (open my $fh, "<", "/proc/cpuinfo") {
483 my %id;
484
485 while (<$fh>) {
486 if (/^core id\s*:\s*(\d+)/) {
487 ++$eus;
488 undef $id{$1};
489 }
490 }
491
492 $cpus = scalar keys %id;
493 } else {
494 $cpus = $eus = @_ ? shift : 1;
495 }
496 wantarray ? ($cpus, $eus) : $cpus
497 };
498 } elsif ($^O eq "freebsd" || $^O eq "netbsd" || $^O eq "openbsd") {
499 *ncpu = sub(;$) {
500 my $cpus = qx<sysctl -n hw.ncpu> * 1
501 || (@_ ? shift : 1);
502 wantarray ? ($cpus, $cpus) : $cpus
503 };
504 } else {
505 *ncpu = sub(;$) {
506 my $cpus = @_ ? shift : 1;
507 wantarray ? ($cpus, $cpus) : $cpus
508 };
509 }
510}
511
451=back 512=back
452 513
453=head1 CHILD USAGE 514=head1 CHILD USAGE
454 515
455In addition to the L<AnyEvent::Fork::RPC> API, this module implements one 516In addition to the L<AnyEvent::Fork::RPC> API, this module implements one
… …
459 520
460=item AnyEvent::Fork::Pool::retire () 521=item AnyEvent::Fork::Pool::retire ()
461 522
462This function sends an event to the parent process to request retirement: 523This function sends an event to the parent process to request retirement:
463the 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,
464but it has to handle the jobs that are already queued. 525but it still has to handle the jobs that are already queued.
465 526
466The 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
467when you compile your code (because that happens I<before> handing the 528when you compile your code (because that happens I<before> handing the
468template 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
469empty parentheses to tell Perl that the function is indeed a function. 530empty parentheses to tell Perl that the function is indeed a function.
470 531
471Retiring 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
472deems this useful. For example, after executing a job, one could check 533deems this useful. For example, after executing a job, it could check the
473the 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
474too 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
475accumulate. 536accumulate.
476 537
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.
542
543 my $count = 0;
544
545 sub my::worker {
546
547 ++$count == 100
548 and AnyEvent::Fork::Pool::retire ();
549
550 ... normal code goes here
551 }
552
477=back 553=back
478 554
479=head1 POOL PARAMETERS RECIPES 555=head1 POOL PARAMETERS RECIPES
480 556
481This section describes some recipes for pool paramaters. These are mostly 557This section describes some recipes for pool parameters. These are mostly
482meant for the synchronous RPC backend, as the asynchronous RPC backend 558meant for the synchronous RPC backend, as the asynchronous RPC backend
483changes the rules considerably, making workers themselves responsible for 559changes the rules considerably, making workers themselves responsible for
484their scheduling. 560their scheduling.
485 561
486=over 4 562=over 4
… …
515=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
516 592
517When 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
518higher throughput, depending very much on your actual workload - sometimes 594higher throughput, depending very much on your actual workload - sometimes
519having 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
520files at maixmum speed, as a second worker will increase seek times. 596files at maximum speed, as a second worker will increase seek times.
521 597
522=back 598=back
523 599
524=head1 EXCEPTIONS 600=head1 EXCEPTIONS
525 601
526The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptins will 602The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptions
527not be caught, and exceptions in both worker and in callbacks causes 603will not be caught, and exceptions in both worker and in callbacks causes
528undesirable or undefined behaviour. 604undesirable or undefined behaviour.
529 605
530=head1 SEE ALSO 606=head1 SEE ALSO
531 607
532L<AnyEvent::Fork>, to create the processes in the first place. 608L<AnyEvent::Fork>, to create the processes in the first place.
609
610L<AnyEvent::Fork::Remote>, likewise, but helpful for remote processes.
533 611
534L<AnyEvent::Fork::RPC>, which implements the RPC protocol and API. 612L<AnyEvent::Fork::RPC>, which implements the RPC protocol and API.
535 613
536=head1 AUTHOR AND CONTACT INFORMATION 614=head1 AUTHOR AND CONTACT INFORMATION
537 615

Diff Legend

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