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.11 by root, Thu Apr 18 07:59:46 2013 UTC vs.
Revision 1.18 by root, Thu Apr 18 20:20:42 2013 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork 3AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork
4
5THE API IS NOT FINISHED, CONSIDER THIS A TECHNOLOGY DEMO
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7 use AnyEvent::Fork::RPC; 9 use AnyEvent::Fork::RPC;
8 # use AnyEvent::Fork is not needed 10 # use AnyEvent::Fork is not needed
… …
11 ->new 13 ->new
12 ->require ("MyModule") 14 ->require ("MyModule")
13 ->AnyEvent::Fork::RPC::run ( 15 ->AnyEvent::Fork::RPC::run (
14 "MyModule::server", 16 "MyModule::server",
15 ); 17 );
18
19 use AnyEvent;
16 20
17 my $cv = AE::cv; 21 my $cv = AE::cv;
18 22
19 $rpc->(1, 2, 3, sub { 23 $rpc->(1, 2, 3, sub {
20 print "MyModule::server returned @_\n"; 24 print "MyModule::server returned @_\n";
… …
372 376
373The default server used in the child does all I/O blockingly, and only 377The default server used in the child does all I/O blockingly, and only
374allows a single RPC call to execute concurrently. 378allows a single RPC call to execute concurrently.
375 379
376Setting C<async> to a true value switches to another implementation that 380Setting C<async> to a true value switches to another implementation that
377uses L<AnyEvent> in the child and allows multiple concurrent RPC calls. 381uses L<AnyEvent> in the child and allows multiple concurrent RPC calls (it
382does not support recursion in the event loop however, blocking condvar
383calls will fail).
378 384
379The actual API in the child is documented in the section that describes 385The actual API in the child is documented in the section that describes
380the calling semantics of the returned C<$rpc> function. 386the calling semantics of the returned C<$rpc> function.
381 387
382If you want to pre-load the actual back-end modules to enable memory 388If you want to pre-load the actual back-end modules to enable memory
… …
384synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode. 390synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode.
385 391
386If you use a template process and want to fork both sync and async 392If you use a template process and want to fork both sync and async
387children, then it is permissible to load both modules. 393children, then it is permissible to load both modules.
388 394
389=item serialiser => $string (default: '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })') 395=item serialiser => $string (default: $AnyEvent::Fork::RPC::STRING_SERIALISER)
390 396
391All arguments, result data and event data have to be serialised to be 397All arguments, result data and event data have to be serialised to be
392transferred between the processes. For this, they have to be frozen and 398transferred between the processes. For this, they have to be frozen and
393thawed in both parent and child processes. 399thawed in both parent and child processes.
394 400
395By default, only octet strings can be passed between the processes, which 401By default, only octet strings can be passed between the processes, which
396is reasonably fast and efficient. 402is reasonably fast and efficient and requires no extra modules.
397 403
398For more complicated use cases, you can provide your own freeze and thaw 404For more complicated use cases, you can provide your own freeze and thaw
399functions, by specifying a string with perl source code. It's supposed to 405functions, by specifying a string with perl source code. It's supposed to
400return two code references when evaluated: the first receives a list of 406return two code references when evaluated: the first receives a list of
401perl values and must return an octet string. The second receives the octet 407perl values and must return an octet string. The second receives the octet
… …
403 409
404If you need an external module for serialisation, then you can either 410If you need an external module for serialisation, then you can either
405pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use> 411pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use>
406or C<require> statement into the serialiser string. Or both. 412or C<require> statement into the serialiser string. Or both.
407 413
414Here are some examples - some of them are also available as global
415variables that make them easier to use.
416
417=over 4
418
419=item octet strings - C<$AnyEvent::Fork::RPC::STRING_SERIALISER>
420
421This serialiser concatenates length-prefixes octet strings, and is the
422default.
423
424Implementation:
425
426 (
427 sub { pack "(w/a*)*", @_ },
428 sub { unpack "(w/a*)*", shift }
429 )
430
431=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER>
432
433This serialiser creates JSON arrays - you have to make sure the L<JSON>
434module is installed for this serialiser to work. It can be beneficial for
435sharing when you preload the L<JSON> module in a template process.
436
437L<JSON> (with L<JSON::XS> installed) is slower than the octet string
438serialiser, but usually much faster than L<Storable>, unless big chunks of
439binary data need to be transferred.
440
441Implementation:
442
443 use JSON ();
444 (
445 sub { JSON::encode_json \@_ },
446 sub { @{ JSON::decode_json shift } }
447 )
448
449=item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER>
450
451This serialiser uses L<Storable>, which means it has high chance of
452serialising just about anything you throw at it, at the cost of having
453very high overhead per operation. It also comes with perl.
454
455Implementation:
456
457 use Storable ();
458 (
459 sub { Storable::freeze \@_ },
460 sub { @{ Storable::thaw shift } }
461 )
462
463=back
464
408=back 465=back
409 466
410See the examples section earlier in this document for some actual 467See the examples section earlier in this document for some actual
411examples. 468examples.
412 469
413=cut 470=cut
414 471
415our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 472our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
473our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })';
474our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
416 475
417sub run { 476sub run {
418 my ($self, $function, %arg) = @_; 477 my ($self, $function, %arg) = @_;
419 478
420 my $serialiser = delete $arg{serialiser} || $STRING_SERIALISER; 479 my $serialiser = delete $arg{serialiser} || $STRING_SERIALISER;
… …
489 } 548 }
490 } elsif (defined $len) { 549 } elsif (defined $len) {
491 undef $rw; undef $ww; # it ends here 550 undef $rw; undef $ww; # it ends here
492 551
493 if (@rcb || %rcb) { 552 if (@rcb || %rcb) {
494 use Data::Dump;ddx[\@rcb,\%rcb];#d#
495 $on_error->("unexpected eof"); 553 $on_error->("unexpected eof");
496 } else { 554 } else {
497 $on_destroy->(); 555 $on_destroy->();
498 } 556 }
499 } elsif ($! != Errno::EAGAIN && $! != Errno::EWOULDBLOCK) { 557 } elsif ($! != Errno::EAGAIN && $! != Errno::EWOULDBLOCK) {
… …
505 $ww ||= AE::io $fh, 1, $wcb; 563 $ww ||= AE::io $fh, 1, $wcb;
506 }); 564 });
507 565
508 my $guard = Guard::guard { 566 my $guard = Guard::guard {
509 $shutdown = 1; 567 $shutdown = 1;
510 $ww ||= $fh && AE::io $fh, 1, $wcb; 568
569 $wcb->() if $fh && !$ww;
511 }; 570 };
512 571
513 my $id; 572 my $id;
514 573
515 $arg{async} 574 $arg{async}
… …
579See the examples section earlier in this document for some actual 638See the examples section earlier in this document for some actual
580examples. 639examples.
581 640
582=back 641=back
583 642
643=head1 ADVANCED TOPICS
644
645=head2 Choosing a backend
646
647So how do you decide which backend to use? Well, that's your problem to
648solve, but here are some thoughts on the matter:
649
650=over 4
651
652=item Synchronous
653
654The synchronous backend does not rely on any external modules (well,
655except L<common::sense>, which works around a bug in how perl's warning
656system works). This keeps the process very small, for example, on my
657system, an empty perl interpreter uses 1492kB RSS, which becomes 2020kB
658after C<use warnings; use strict> (for people who grew up with C64s around
659them this is probably shocking every single time they see it). The worker
660process in the first example in this document uses 1792kB.
661
662Since the calls are done synchronously, slow jobs will keep newer jobs
663from executing.
664
665The synchronous backend also has no overhead due to running an event loop
666- reading requests is therefore very efficient, while writing responses is
667less so, as every response results in a write syscall.
668
669If the parent process is busy and a bit slow reading responses, the child
670waits instead of processing further requests. This also limits the amount
671of memory needed for buffering, as never more than one response has to be
672buffered.
673
674The API in the child is simple - you just have to define a function that
675does something and returns something.
676
677It's hard to use modules or code that relies on an event loop, as the
678child cannot execute anything while it waits for more input.
679
680=item Asynchronous
681
682The asynchronous backend relies on L<AnyEvent>, which tries to be small,
683but still comes at a price: On my system, the worker from example 1a uses
6843420kB RSS (for L<AnyEvent>, which loads L<EV>, which needs L<XSLoader>
685which in turn loads a lot of other modules such as L<warnings>, L<strict>,
686L<vars>, L<Exporter>...).
687
688It batches requests and responses reasonably efficiently, doing only as
689few reads and writes as needed, but needs to poll for events via the event
690loop.
691
692Responses are queued when the parent process is busy. This means the child
693can continue to execute any queued requests. It also means that a child
694might queue a lot of responses in memory when it generates them and the
695parent process is slow accepting them.
696
697The API is not a straightforward RPC pattern - you have to call a
698"done" callback to pass return values and signal completion. Also, more
699importantly, the API starts jobs as fast as possible - when 1000 jobs
700are queued and the jobs are slow, they will all run concurrently. The
701child must implement some queueing/limiting mechanism if this causes
702problems. Alternatively, the parent could limit the amount of rpc calls
703that are outstanding.
704
705Blocking use of condvars is not supported.
706
707Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
708easy.
709
710=back
711
712=head2 Passing file descriptors
713
714Unlike L<AnyEvent::Fork>, this module has no in-built file handle or file
715descriptor passing abilities.
716
717The reason is that passing file descriptors is extraordinary tricky
718business, and conflicts with efficient batching of messages.
719
720There still is a method you can use: Create a
721C<AnyEvent::Util::portable_socketpair> and C<send_fh> one half of it to
722the process before you pass control to C<AnyEvent::Fork::RPC::run>.
723
724Whenever you want to pass a file descriptor, send an rpc request to the
725child process (so it expects the descriptor), then send it over the other
726half of the socketpair. The child should fetch the descriptor from the
727half it has passed earlier.
728
729Here is some (untested) pseudocode to that effect:
730
731 use AnyEvent::Util;
732 use AnyEvent::Fork::RPC;
733 use IO::FDPass;
734
735 my ($s1, $s2) = AnyEvent::Util::portable_socketpair;
736
737 my $rpc = AnyEvent::Fork
738 ->new
739 ->send_fh ($s2)
740 ->require ("MyWorker")
741 ->AnyEvent::Fork::RPC::run ("MyWorker::run"
742 init => "MyWorker::init",
743 );
744
745 undef $s2; # no need to keep it around
746
747 # pass an fd
748 $rpc->("i'll send some fd now, please expect it!", my $cv = AE::cv);
749
750 IO::FDPass fileno $s1, fileno $handle_to_pass;
751
752 $cv->recv;
753
754The MyWorker module could look like this:
755
756 package MyWorker;
757
758 use IO::FDPass;
759
760 my $s2;
761
762 sub init {
763 $s2 = $_[0];
764 }
765
766 sub run {
767 if ($_[0] eq "i'll send some fd now, please expect it!") {
768 my $fd = IO::FDPass::recv fileno $s2;
769 ...
770 }
771 }
772
773Of course, this might be blocking if you pass a lot of file descriptors,
774so you might want to look into L<AnyEvent::FDpasser> which can handle the
775gory details.
776
584=head1 SEE ALSO 777=head1 SEE ALSO
585 778
586L<AnyEvent::Fork> (to create the processes in the first place), 779L<AnyEvent::Fork>, to create the processes in the first place.
780
587L<AnyEvent::Fork::Pool> (to manage whole pools of processes). 781L<AnyEvent::Fork::Pool>, to manage whole pools of processes.
588 782
589=head1 AUTHOR AND CONTACT INFORMATION 783=head1 AUTHOR AND CONTACT INFORMATION
590 784
591 Marc Lehmann <schmorp@schmorp.de> 785 Marc Lehmann <schmorp@schmorp.de>
592 http://software.schmorp.de/pkg/AnyEvent-Fork-RPC 786 http://software.schmorp.de/pkg/AnyEvent-Fork-RPC

Diff Legend

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