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

Comparing AnyEvent-Fork-RPC/RPC.pm (file contents):
Revision 1.30 by root, Sun Aug 25 22:21:15 2013 UTC vs.
Revision 1.35 by root, Wed Nov 20 16:17:22 2013 UTC

… …
175you really I<are> done. 175you really I<are> done.
176 176
177=head2 Example 2: Asynchronous Backend 177=head2 Example 2: Asynchronous Backend
178 178
179This example implements multiple count-downs in the child, using 179This example implements multiple count-downs in the child, using
180L<AnyEvent> timers. While this is a bit silly (one could use timers in te 180L<AnyEvent> timers. While this is a bit silly (one could use timers in the
181parent just as well), it illustrates the ability to use AnyEvent in the 181parent just as well), it illustrates the ability to use AnyEvent in the
182child and the fact that responses can arrive in a different order then the 182child and the fact that responses can arrive in a different order then the
183requests. 183requests.
184 184
185It also shows how to embed the actual child code into a C<__DATA__> 185It also shows how to embed the actual child code into a C<__DATA__>
… …
391use Errno (); 391use Errno ();
392use Guard (); 392use Guard ();
393 393
394use AnyEvent; 394use AnyEvent;
395 395
396our $VERSION = 1.1; 396our $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
400The traditional way to call it. But it is way cooler to call it in the 400The traditional way to call it. But it is way cooler to call it in the
401following way: 401following way:
… …
454It is called very early - before the serialisers are created or the 454It is called very early - before the serialisers are created or the
455C<$function> name is resolved into a function reference, so it could be 455C<$function> name is resolved into a function reference, so it could be
456used to load any modules that provide the serialiser or function. It can 456used to load any modules that provide the serialiser or function. It can
457not, however, create events. 457not, however, create events.
458 458
459=item done => $function (default C<CORE::exit>)
460
461The function to call when the asynchronous backend detects an end of file
462condition when reading from the communications socket I<and> there are no
463outstanding requests. It's ignored by the synchronous backend.
464
465By overriding this you can prolong the life of a RPC process after e.g.
466the 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
468could provide L<EV::loop> as C<done> function).
469
470Of course, in that case you are responsible for exiting at the appropriate
471time and not returning from
472
459=item async => $boolean (default: 0) 473=item async => $boolean (default: 0)
460 474
461The default server used in the child does all I/O blockingly, and only 475The default server used in the child does all I/O blockingly, and only
462allows a single RPC call to execute concurrently. 476allows a single RPC call to execute concurrently.
463 477
… …
511 ( 525 (
512 sub { pack "(w/a*)*", @_ }, 526 sub { pack "(w/a*)*", @_ },
513 sub { unpack "(w/a*)*", shift } 527 sub { unpack "(w/a*)*", shift }
514 ) 528 )
515 529
530=item json - C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER>
531
532This serialiser creates CBOR::XS arrays - you have to make sure the
533L<CBOR::XS> module is installed for this serialiser to work. It can be
534beneficial for sharing when you preload the L<CBOR::XS> module in a template
535process.
536
537L<CBOR::XS> is about as fast as the octet string serialiser, but supports
538complex data structures (similar to JSON) and is faster than any of the
539other serialisers. If you have the L<CBOR::XS> module available, it's the
540best choice.
541
542Note that the CBOR::XS module supports some extensions to encode cyclic
543and self-referencing data structures, which are not enabled. You need to
544write your own serialiser to take advantage of these.
545
546Implementation:
547
548 use CBOR::XS ();
549 (
550 sub { CBOR::XS::encode_cbor \@_ },
551 sub { @{ CBOR::XS::decode_cbor shift } }
552 )
553
516=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER> 554=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER>
517 555
518This serialiser creates JSON arrays - you have to make sure the L<JSON> 556This serialiser creates JSON arrays - you have to make sure the L<JSON>
519module is installed for this serialiser to work. It can be beneficial for 557module is installed for this serialiser to work. It can be beneficial for
520sharing when you preload the L<JSON> module in a template process. 558sharing when you preload the L<JSON> module in a template process.
… …
569examples. 607examples.
570 608
571=cut 609=cut
572 610
573our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 611our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
612our $CBOR_XS_SERIALISER = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
574our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })'; 613our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })';
575our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })'; 614our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
576our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })'; 615our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })';
577 616
578sub run { 617sub run {
579 my ($self, $function, %arg) = @_; 618 my ($self, $function, %arg) = @_;
… …
615 }; 654 };
616 655
617 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); 656 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync");
618 657
619 $self->require ($module) 658 $self->require ($module)
620 ->send_arg ($function, $arg{init}, $serialiser) 659 ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "$module\::do_exit")
621 ->run ("$module\::run", sub { 660 ->run ("$module\::run", sub {
622 $fh = shift; 661 $fh = shift;
623 662
624 my ($id, $len); 663 my ($id, $len);
625 $rw = AE::io $fh, 0, sub { 664 $rw = AE::io $fh, 0, sub {
… …
741See the examples section earlier in this document for some actual 780See the examples section earlier in this document for some actual
742examples. 781examples.
743 782
744=back 783=back
745 784
785=head2 PROCESS EXIT
786
787If and when the child process exits depends on the backend and
788configuration. Apart from explicit exits (e.g. by calling C<exit>) or
789runtime conditions (uncaught exceptions, signals etc.), the backends exit
790under these conditions:
791
792=over 4
793
794=item Synchronous Backend
795
796The synchronous backend is very simple: when the process waits for another
797request to arrive and the writing side (usually in the parent) is closed,
798it will exit normally, i.e. as if your main program reached the end of the
799file.
800
801That means that if your parent process exits, the RPC process will usually
802exit as well, either because it is idle anyway, or because it executes a
803request. In the latter case, you will likely get an error when the RPc
804process tries to send the results to the parent (because agruably, you
805shouldn't exit your parent while there are still outstanding requests).
806
807The process is usually quiescent when it happens, so it should rarely be a
808problem, and C<END> handlers can be used to clean up.
809
810=item Asynchronous Backend
811
812For the asynchronous backend, things are more complicated: Whenever it
813listens for another request by the parent, it might detect that the socket
814was closed (e.g. because the parent exited). It will sotp listening for
815new requests and instead try to write out any remaining data (if any) or
816simply check whether the socket can be written to. After this, the RPC
817process is effectively done - no new requests are incoming, no outstanding
818request data can be written back.
819
820Since chances are high that there are event watchers that the RPC server
821knows nothing about (why else would one use the async backend if not for
822the ability to register watchers?), the event loop would often happily
823continue.
824
825This is why the asynchronous backend explicitly calls C<CORE::exit> when
826it is done (under other circumstances, such as when there is an I/O error
827and there is outstanding data to write, it will log a fatal message via
828L<AnyEvent::Log>, also causing the program to exit).
829
830You can override this by specifying a function name to call via the C<done>
831parameter instead.
832
833=back
834
746=head1 ADVANCED TOPICS 835=head1 ADVANCED TOPICS
747 836
748=head2 Choosing a backend 837=head2 Choosing a backend
749 838
750So how do you decide which backend to use? Well, that's your problem to 839So how do you decide which backend to use? Well, that's your problem to

Diff Legend

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