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.29 by root, Sun Aug 25 21:52:15 2013 UTC vs.
Revision 1.36 by root, Sat Nov 30 17:41:46 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__>
… …
336 $rpc->(add => 1, 3, Coro::rouse_cb); say Coro::rouse_wait; 336 $rpc->(add => 1, 3, Coro::rouse_cb); say Coro::rouse_wait;
337 $rpc->(mul => 3, 2, Coro::rouse_cb); say Coro::rouse_wait; 337 $rpc->(mul => 3, 2, Coro::rouse_cb); say Coro::rouse_wait;
338 338
339The C<say>'s will print C<4> and C<6>. 339The C<say>'s will print C<4> and C<6>.
340 340
341=head2 Example 4: Forward AnyEvent::Log messages using C<on_event>
342
343This partial example shows how to use the C<event> function to forward
344L<AnyEvent::Log> messages to the parent.
345
346For this, the parent needs to provide a suitable C<on_event>:
347
348 ->AnyEvent::Fork::RPC::run (
349 on_event => sub {
350 if ($_[0] eq "ae_log") {
351 my (undef, $level, $message) = @_;
352 AE::log $level, $message;
353 } else {
354 # other event types
355 }
356 },
357 )
358
359In the child, as early as possible, the following code should reconfigure
360L<AnyEvent::Log> to log via C<AnyEvent::Fork::RPC::event>:
361
362 $AnyEvent::Log::LOG->log_cb (sub {
363 my ($timestamp, $orig_ctx, $level, $message) = @{+shift};
364
365 if (defined &AnyEvent::Fork::RPC::event) {
366 AnyEvent::Fork::RPC::event (ae_log => $level, $message);
367 } else {
368 warn "[$$ before init] $message\n";
369 }
370 });
371
372There is an important twist - the C<AnyEvent::Fork::RPC::event> function
373is only defined when the child is fully initialised. If you redirect the
374log messages in your C<init> function for example, then the C<event>
375function might not yet be available. This is why the log callback checks
376whether the fucntion is there using C<defined>, and only then uses it to
377log the message.
378
341=head1 PARENT PROCESS USAGE 379=head1 PARENT PROCESS USAGE
342 380
343This module exports nothing, and only implements a single function: 381This module exports nothing, and only implements a single function:
344 382
345=over 4 383=over 4
… …
353use Errno (); 391use Errno ();
354use Guard (); 392use Guard ();
355 393
356use AnyEvent; 394use AnyEvent;
357 395
358our $VERSION = 1.1; 396our $VERSION = 1.21;
359 397
360=item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...] 398=item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...]
361 399
362The 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
363following way: 401following way:
… …
416It is called very early - before the serialisers are created or the 454It is called very early - before the serialisers are created or the
417C<$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
418used 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
419not, however, create events. 457not, however, create events.
420 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
421=item async => $boolean (default: 0) 473=item async => $boolean (default: 0)
422 474
423The 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
424allows a single RPC call to execute concurrently. 476allows a single RPC call to execute concurrently.
425 477
… …
442 494
443All arguments, result data and event data have to be serialised to be 495All arguments, result data and event data have to be serialised to be
444transferred between the processes. For this, they have to be frozen and 496transferred between the processes. For this, they have to be frozen and
445thawed in both parent and child processes. 497thawed in both parent and child processes.
446 498
447By default, only octet strings can be passed between the processes, which 499By default, only octet strings can be passed between the processes,
448is reasonably fast and efficient and requires no extra modules. 500which is reasonably fast and efficient and requires no extra modules
501(the C<AnyEvent::Fork::RPC> distribution does not provide these extra
502serialiser modules).
449 503
450For more complicated use cases, you can provide your own freeze and thaw 504For more complicated use cases, you can provide your own freeze and thaw
451functions, by specifying a string with perl source code. It's supposed to 505functions, by specifying a string with perl source code. It's supposed to
452return two code references when evaluated: the first receives a list of 506return two code references when evaluated: the first receives a list of
453perl values and must return an octet string. The second receives the octet 507perl values and must return an octet string. The second receives the octet
… …
473 ( 527 (
474 sub { pack "(w/a*)*", @_ }, 528 sub { pack "(w/a*)*", @_ },
475 sub { unpack "(w/a*)*", shift } 529 sub { unpack "(w/a*)*", shift }
476 ) 530 )
477 531
532=item cbor - C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER>
533
534This serialiser creates CBOR::XS arrays - you have to make sure the
535L<CBOR::XS> module is installed for this serialiser to work. It can be
536beneficial for sharing when you preload the L<CBOR::XS> module in a template
537process.
538
539L<CBOR::XS> is about as fast as the octet string serialiser, but supports
540complex data structures (similar to JSON) and is faster than any of the
541other serialisers. If you have the L<CBOR::XS> module available, it's the
542best choice.
543
544The encoder enables C<allow_sharing> (so this serialisation method can
545encode cyclic and self-referencing data structures).
546
547Implementation:
548
549 use CBOR::XS ();
550 (
551 sub { CBOR::XS::encode_cbor_sharing \@_ },
552 sub { @{ CBOR::XS::decode_cbor shift } }
553 )
554
478=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER> 555=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER>
479 556
480This serialiser creates JSON arrays - you have to make sure the L<JSON> 557This serialiser creates JSON arrays - you have to make sure the L<JSON>
481module is installed for this serialiser to work. It can be beneficial for 558module is installed for this serialiser to work. It can be beneficial for
482sharing when you preload the L<JSON> module in a template process. 559sharing when you preload the L<JSON> module in a template process.
… …
531examples. 608examples.
532 609
533=cut 610=cut
534 611
535our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 612our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
613our $CBOR_XS_SERIALISER = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor_sharing \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
536our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })'; 614our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })';
537our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })'; 615our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
538our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })'; 616our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })';
539 617
540sub run { 618sub run {
541 my ($self, $function, %arg) = @_; 619 my ($self, $function, %arg) = @_;
… …
577 }; 655 };
578 656
579 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); 657 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync");
580 658
581 $self->require ($module) 659 $self->require ($module)
582 ->send_arg ($function, $arg{init}, $serialiser) 660 ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "$module\::do_exit")
583 ->run ("$module\::run", sub { 661 ->run ("$module\::run", sub {
584 $fh = shift; 662 $fh = shift;
585 663
586 my ($id, $len); 664 my ($id, $len);
587 $rw = AE::io $fh, 0, sub { 665 $rw = AE::io $fh, 0, sub {
… …
703See the examples section earlier in this document for some actual 781See the examples section earlier in this document for some actual
704examples. 782examples.
705 783
706=back 784=back
707 785
786=head2 PROCESS EXIT
787
788If and when the child process exits depends on the backend and
789configuration. Apart from explicit exits (e.g. by calling C<exit>) or
790runtime conditions (uncaught exceptions, signals etc.), the backends exit
791under these conditions:
792
793=over 4
794
795=item Synchronous Backend
796
797The synchronous backend is very simple: when the process waits for another
798request to arrive and the writing side (usually in the parent) is closed,
799it will exit normally, i.e. as if your main program reached the end of the
800file.
801
802That means that if your parent process exits, the RPC process will usually
803exit as well, either because it is idle anyway, or because it executes a
804request. In the latter case, you will likely get an error when the RPc
805process tries to send the results to the parent (because agruably, you
806shouldn't exit your parent while there are still outstanding requests).
807
808The process is usually quiescent when it happens, so it should rarely be a
809problem, and C<END> handlers can be used to clean up.
810
811=item Asynchronous Backend
812
813For the asynchronous backend, things are more complicated: Whenever it
814listens for another request by the parent, it might detect that the socket
815was closed (e.g. because the parent exited). It will sotp listening for
816new requests and instead try to write out any remaining data (if any) or
817simply check whether the socket can be written to. After this, the RPC
818process is effectively done - no new requests are incoming, no outstanding
819request data can be written back.
820
821Since chances are high that there are event watchers that the RPC server
822knows nothing about (why else would one use the async backend if not for
823the ability to register watchers?), the event loop would often happily
824continue.
825
826This is why the asynchronous backend explicitly calls C<CORE::exit> when
827it is done (under other circumstances, such as when there is an I/O error
828and there is outstanding data to write, it will log a fatal message via
829L<AnyEvent::Log>, also causing the program to exit).
830
831You can override this by specifying a function name to call via the C<done>
832parameter instead.
833
834=back
835
708=head1 ADVANCED TOPICS 836=head1 ADVANCED TOPICS
709 837
710=head2 Choosing a backend 838=head2 Choosing a backend
711 839
712So how do you decide which backend to use? Well, that's your problem to 840So how do you decide which backend to use? Well, that's your problem to

Diff Legend

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