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