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.10 by root, Thu Apr 25 01:21:18 2013 UTC vs.
Revision 1.14 by root, Sun Oct 26 16:22:38 2014 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 of L<AnyEvent::Fork> is helpful but not critical to be able
53to use this module, but a thorough understanding of L<AnyEvent::Fork::RPC> 52to use this module, but a thorough understanding of L<AnyEvent::Fork::RPC>
54is, as it defines the actual API that needs to be implemented in the 53is, as it defines the actual API that needs to be implemented in the
55worker processes. 54worker processes.
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;
94# explicit version on next line, as some cpan-testers test with the 0.1 version,
95# ignoring dependencies, and this line will at least give a clear indication of that.
96use AnyEvent::Fork 0.6; # we don't actually depend on it, this is for convenience
97use AnyEvent::Fork::RPC; 91use AnyEvent::Fork::RPC;
98 92
99# these are used for the first and last argument of events 93# these are used for the first and last argument of events
100# 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,
101# but didn't come up with an obviously better alternative. 95# but didn't come up with an obviously better alternative.
102my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P'; 96my $magic0 = ':t6Z@HK1N%Dx@_7?=~-7NQgWDdAs6a,jFN=wLO0*jD*1%P';
103my $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*';
104 98
105our $VERSION = 0.1; 99our $VERSION = 1.1;
106 100
107=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...] 101=item my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...]
108 102
109The 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
110cooler to call it in the following way: 104cooler to call it in the following way:
… …
452 446
453=item $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus] 447=item $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus]
454 448
455=item ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus] 449=item ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus]
456 450
457Tries to detect the number of CPUs (C<$cpus> often called cpu cores 451Tries to detect the number of CPUs (C<$cpus> often called CPU cores
458nowadays) and execution units (C<$eus>) which include e.g. extra 452nowadays) and execution units (C<$eus>) which include e.g. extra
459hyperthreaded units). When C<$cpus> cannot be determined reliably, 453hyperthreaded units). When C<$cpus> cannot be determined reliably,
460C<$default_cpus> is returned for both values, or C<1> if it is missing. 454C<$default_cpus> is returned for both values, or C<1> if it is missing.
461 455
462For normal CPU bound uses, it is wise to have as many worker processes 456For normal CPU bound uses, it is wise to have as many worker processes
… …
464hyperthreading is usually detrimental to performance, but in those rare 458hyperthreading is usually detrimental to performance, but in those rare
465cases where that really helps it might be beneficial to use more workers 459cases where that really helps it might be beneficial to use more workers
466(C<$eus>). 460(C<$eus>).
467 461
468Currently, F</proc/cpuinfo> is parsed on GNU/Linux systems for both 462Currently, F</proc/cpuinfo> is parsed on GNU/Linux systems for both
469C<$cpus> and C<$eu>, and on {Free,Net,Open}BSD, F<sysctl -n hw.ncpu> is 463C<$cpus> and C<$eus>, and on {Free,Net,Open}BSD, F<sysctl -n hw.ncpu> is
470used for C<$cpus>. 464used for C<$cpus>.
471 465
472Example: create a worker pool with as many workers as cpu cores, or C<2>, 466Example: create a worker pool with as many workers as CPU cores, or C<2>,
473if the actual number could not be determined. 467if the actual number could not be determined.
474 468
475 $fork->AnyEvent::Fork::Pool::run ("myworker::function", 469 $fork->AnyEvent::Fork::Pool::run ("myworker::function",
476 max => (scalar AnyEvent::Fork::Pool::ncpu 2), 470 max => (scalar AnyEvent::Fork::Pool::ncpu 2),
477 ); 471 );
… …
524 518
525=item AnyEvent::Fork::Pool::retire () 519=item AnyEvent::Fork::Pool::retire ()
526 520
527This function sends an event to the parent process to request retirement: 521This function sends an event to the parent process to request retirement:
528the worker is removed from the pool and no new jobs will be sent to it, 522the worker is removed from the pool and no new jobs will be sent to it,
529but it has to handle the jobs that are already queued. 523but it still has to handle the jobs that are already queued.
530 524
531The parentheses are part of the syntax: the function usually isn't defined 525The parentheses are part of the syntax: the function usually isn't defined
532when you compile your code (because that happens I<before> handing the 526when you compile your code (because that happens I<before> handing the
533template process over to C<AnyEvent::Fork::Pool::run>, so you need the 527template process over to C<AnyEvent::Fork::Pool::run>, so you need the
534empty parentheses to tell Perl that the function is indeed a function. 528empty parentheses to tell Perl that the function is indeed a function.
535 529
536Retiring a worker can be useful to gracefully shut it down when the worker 530Retiring a worker can be useful to gracefully shut it down when the worker
537deems this useful. For example, after executing a job, one could check 531deems this useful. For example, after executing a job, it could check the
538the process size or the number of jobs handled so far, and if either is 532process size or the number of jobs handled so far, and if either is too
539too high, the worker could ask to get retired, to avoid memory leaks to 533high, the worker could request to be retired, to avoid memory leaks to
540accumulate. 534accumulate.
541 535
542Example: retire a worker after it has handled roughly 100 requests. 536Example: retire a worker after it has handled roughly 100 requests. It
537doesn't matter whether you retire at the beginning or end of your request,
538as the worker will continue to handle some outstanding requests. Likewise,
539it's ok to call retire multiple times.
543 540
544 my $count = 0; 541 my $count = 0;
545 542
546 sub my::worker { 543 sub my::worker {
547 544
… …
553 550
554=back 551=back
555 552
556=head1 POOL PARAMETERS RECIPES 553=head1 POOL PARAMETERS RECIPES
557 554
558This section describes some recipes for pool paramaters. These are mostly 555This section describes some recipes for pool parameters. These are mostly
559meant for the synchronous RPC backend, as the asynchronous RPC backend 556meant for the synchronous RPC backend, as the asynchronous RPC backend
560changes the rules considerably, making workers themselves responsible for 557changes the rules considerably, making workers themselves responsible for
561their scheduling. 558their scheduling.
562 559
563=over 4 560=over 4
… …
592=item high throughput, I/O bound jobs - set load >= 2, max = 1, or very high 589=item high throughput, I/O bound jobs - set load >= 2, max = 1, or very high
593 590
594When your jobs are I/O bound, using more workers usually boils down to 591When your jobs are I/O bound, using more workers usually boils down to
595higher throughput, depending very much on your actual workload - sometimes 592higher throughput, depending very much on your actual workload - sometimes
596having only one worker is best, for example, when you read or write big 593having only one worker is best, for example, when you read or write big
597files at maixmum speed, as a second worker will increase seek times. 594files at maximum speed, as a second worker will increase seek times.
598 595
599=back 596=back
600 597
601=head1 EXCEPTIONS 598=head1 EXCEPTIONS
602 599
603The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptins will 600The same "policy" as with L<AnyEvent::Fork::RPC> applies - exceptions
604not be caught, and exceptions in both worker and in callbacks causes 601will not be caught, and exceptions in both worker and in callbacks causes
605undesirable or undefined behaviour. 602undesirable or undefined behaviour.
606 603
607=head1 SEE ALSO 604=head1 SEE ALSO
608 605
609L<AnyEvent::Fork>, to create the processes in the first place. 606L<AnyEvent::Fork>, to create the processes in the first place.
607
608L<AnyEvent::Fork::Remote>, likewise, but helpful for remote processes.
610 609
611L<AnyEvent::Fork::RPC>, which implements the RPC protocol and API. 610L<AnyEvent::Fork::RPC>, which implements the RPC protocol and API.
612 611
613=head1 AUTHOR AND CONTACT INFORMATION 612=head1 AUTHOR AND CONTACT INFORMATION
614 613

Diff Legend

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