| … | |
… | |
| 175 | you really I<are> done. |
175 | you really I<are> done. |
| 176 | |
176 | |
| 177 | =head2 Example 2: Asynchronous Backend |
177 | =head2 Example 2: Asynchronous Backend |
| 178 | |
178 | |
| 179 | This example implements multiple count-downs in the child, using |
179 | This example implements multiple count-downs in the child, using |
| 180 | L<AnyEvent> timers. While this is a bit silly (one could use timers in te |
180 | L<AnyEvent> timers. While this is a bit silly (one could use timers in the |
| 181 | parent just as well), it illustrates the ability to use AnyEvent in the |
181 | parent just as well), it illustrates the ability to use AnyEvent in the |
| 182 | child and the fact that responses can arrive in a different order then the |
182 | child and the fact that responses can arrive in a different order then the |
| 183 | requests. |
183 | requests. |
| 184 | |
184 | |
| 185 | It also shows how to embed the actual child code into a C<__DATA__> |
185 | It also shows how to embed the actual child code into a C<__DATA__> |
| … | |
… | |
| 391 | use Errno (); |
391 | use Errno (); |
| 392 | use Guard (); |
392 | use Guard (); |
| 393 | |
393 | |
| 394 | use AnyEvent; |
394 | use AnyEvent; |
| 395 | |
395 | |
| 396 | our $VERSION = 1.1; |
396 | our $VERSION = 1.21; |
| 397 | |
397 | |
| 398 | =item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...] |
398 | =item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...] |
| 399 | |
399 | |
| 400 | The traditional way to call it. But it is way cooler to call it in the |
400 | The traditional way to call it. But it is way cooler to call it in the |
| 401 | following way: |
401 | following way: |
| … | |
… | |
| 453 | |
453 | |
| 454 | It is called very early - before the serialisers are created or the |
454 | It is called very early - before the serialisers are created or the |
| 455 | C<$function> name is resolved into a function reference, so it could be |
455 | C<$function> name is resolved into a function reference, so it could be |
| 456 | used to load any modules that provide the serialiser or function. It can |
456 | used to load any modules that provide the serialiser or function. It can |
| 457 | not, however, create events. |
457 | not, however, create events. |
|
|
458 | |
|
|
459 | =item done => $function (default C<CORE::exit>) |
|
|
460 | |
|
|
461 | The function to call when the asynchronous backend detects an end of file |
|
|
462 | condition when reading from the communications socket I<and> there are no |
|
|
463 | outstanding requests. It's ignored by the synchronous backend. |
|
|
464 | |
|
|
465 | By overriding this you can prolong the life of a RPC process after e.g. |
|
|
466 | the parent has exited by running the event loop in the provided function |
|
|
467 | (or simply calling it, for example, when your child process uses L<EV> you |
|
|
468 | could provide L<EV::loop> as C<done> function). |
|
|
469 | |
|
|
470 | Of course, in that case you are responsible for exiting at the appropriate |
|
|
471 | time and not returning from |
| 458 | |
472 | |
| 459 | =item async => $boolean (default: 0) |
473 | =item async => $boolean (default: 0) |
| 460 | |
474 | |
| 461 | The default server used in the child does all I/O blockingly, and only |
475 | The default server used in the child does all I/O blockingly, and only |
| 462 | allows a single RPC call to execute concurrently. |
476 | allows a single RPC call to execute concurrently. |
| … | |
… | |
| 615 | }; |
629 | }; |
| 616 | |
630 | |
| 617 | my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); |
631 | my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); |
| 618 | |
632 | |
| 619 | $self->require ($module) |
633 | $self->require ($module) |
| 620 | ->send_arg ($function, $arg{init}, $serialiser) |
634 | ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "$module\::do_exit") |
| 621 | ->run ("$module\::run", sub { |
635 | ->run ("$module\::run", sub { |
| 622 | $fh = shift; |
636 | $fh = shift; |
| 623 | |
637 | |
| 624 | my ($id, $len); |
638 | my ($id, $len); |
| 625 | $rw = AE::io $fh, 0, sub { |
639 | $rw = AE::io $fh, 0, sub { |
| … | |
… | |
| 741 | See the examples section earlier in this document for some actual |
755 | See the examples section earlier in this document for some actual |
| 742 | examples. |
756 | examples. |
| 743 | |
757 | |
| 744 | =back |
758 | =back |
| 745 | |
759 | |
|
|
760 | =head2 PROCESS EXIT |
|
|
761 | |
|
|
762 | If and when the child process exits depends on the backend and |
|
|
763 | configuration. Apart from explicit exits (e.g. by calling C<exit>) or |
|
|
764 | runtime conditions (uncaught exceptions, signals etc.), the backends exit |
|
|
765 | under these conditions: |
|
|
766 | |
|
|
767 | =over 4 |
|
|
768 | |
|
|
769 | =item Synchronous Backend |
|
|
770 | |
|
|
771 | The synchronous backend is very simple: when the process waits for another |
|
|
772 | request to arrive and the writing side (usually in the parent) is closed, |
|
|
773 | it will exit normally, i.e. as if your main program reached the end of the |
|
|
774 | file. |
|
|
775 | |
|
|
776 | That means that if your parent process exits, the RPC process will usually |
|
|
777 | exit as well, either because it is idle anyway, or because it executes a |
|
|
778 | request. In the latter case, you will likely get an error when the RPc |
|
|
779 | process tries to send the results to the parent (because agruably, you |
|
|
780 | shouldn't exit your parent while there are still outstanding requests). |
|
|
781 | |
|
|
782 | The process is usually quiescent when it happens, so it should rarely be a |
|
|
783 | problem, and C<END> handlers can be used to clean up. |
|
|
784 | |
|
|
785 | =item Asynchronous Backend |
|
|
786 | |
|
|
787 | For the asynchronous backend, things are more complicated: Whenever it |
|
|
788 | listens for another request by the parent, it might detect that the socket |
|
|
789 | was closed (e.g. because the parent exited). It will sotp listening for |
|
|
790 | new requests and instead try to write out any remaining data (if any) or |
|
|
791 | simply check whether the socket can be written to. After this, the RPC |
|
|
792 | process is effectively done - no new requests are incoming, no outstanding |
|
|
793 | request data can be written back. |
|
|
794 | |
|
|
795 | Since chances are high that there are event watchers that the RPC server |
|
|
796 | knows nothing about (why else would one use the async backend if not for |
|
|
797 | the ability to register watchers?), the event loop would often happily |
|
|
798 | continue. |
|
|
799 | |
|
|
800 | This is why the asynchronous backend explicitly calls C<CORE::exit> when |
|
|
801 | it is done (under other circumstances, such as when there is an I/O error |
|
|
802 | and there is outstanding data to write, it will log a fatal message via |
|
|
803 | L<AnyEvent::Log>, also causing the program to exit). |
|
|
804 | |
|
|
805 | You can override this by specifying a function name to call via the C<done> |
|
|
806 | parameter instead. |
|
|
807 | |
|
|
808 | =back |
|
|
809 | |
| 746 | =head1 ADVANCED TOPICS |
810 | =head1 ADVANCED TOPICS |
| 747 | |
811 | |
| 748 | =head2 Choosing a backend |
812 | =head2 Choosing a backend |
| 749 | |
813 | |
| 750 | So how do you decide which backend to use? Well, that's your problem to |
814 | So how do you decide which backend to use? Well, that's your problem to |
