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.31 by root, Sat Aug 31 16:35:33 2013 UTC vs.
Revision 1.42 by root, Tue Mar 26 04:07:02 2019 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.23;
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:
… …
463outstanding requests. It's ignored by the synchronous backend. 463outstanding requests. It's ignored by the synchronous backend.
464 464
465By overriding this you can prolong the life of a RPC process after e.g. 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 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 467(or simply calling it, for example, when your child process uses L<EV> you
468could provide L<EV::loop> as C<done> function). 468could provide L<EV::run> as C<done> function).
469 469
470Of course, in that case you are responsible for exiting at the appropriate 470Of course, in that case you are responsible for exiting at the appropriate
471time and not returning from 471time and not returning from
472 472
473=item async => $boolean (default: 0) 473=item async => $boolean (default: 0)
… …
494 494
495All 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
496transferred between the processes. For this, they have to be frozen and 496transferred between the processes. For this, they have to be frozen and
497thawed in both parent and child processes. 497thawed in both parent and child processes.
498 498
499By default, only octet strings can be passed between the processes, which 499By default, only octet strings can be passed between the processes,
500is 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).
501 503
502For 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
503functions, 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
504return two code references when evaluated: the first receives a list of 506return two code references when evaluated: the first receives a list of
505perl 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
… …
507 509
508If you need an external module for serialisation, then you can either 510If you need an external module for serialisation, then you can either
509pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use> 511pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use>
510or C<require> statement into the serialiser string. Or both. 512or C<require> statement into the serialiser string. Or both.
511 513
512Here are some examples - some of them are also available as global 514Here are some examples - all of them are also available as global
513variables that make them easier to use. 515variables that make them easier to use.
514 516
515=over 4 517=over 4
516 518
517=item octet strings - C<$AnyEvent::Fork::RPC::STRING_SERIALISER> 519=item C<$AnyEvent::Fork::RPC::STRING_SERIALISER> - octet strings only
518 520
519This serialiser concatenates length-prefixes octet strings, and is the 521This serialiser (currently the default) concatenates length-prefixes octet
520default. That means you can only pass (and return) strings containing 522strings, and is the default. That means you can only pass (and return)
521character codes 0-255. 523strings containing character codes 0-255.
524
525The main advantages of this serialiser are the high speed and that it
526doesn't need another module. The main disadvantage is that you are very
527limited in what you can pass - only octet strings.
522 528
523Implementation: 529Implementation:
524 530
525 ( 531 (
526 sub { pack "(w/a*)*", @_ }, 532 sub { pack "(w/a*)*", @_ },
527 sub { unpack "(w/a*)*", shift } 533 sub { unpack "(w/a*)*", shift }
528 ) 534 )
529 535
530=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER> 536=item C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER> - uses L<CBOR::XS>
537
538This serialiser creates CBOR::XS arrays - you have to make sure the
539L<CBOR::XS> module is installed for this serialiser to work. It can be
540beneficial for sharing when you preload the L<CBOR::XS> module in a template
541process.
542
543L<CBOR::XS> is about as fast as the octet string serialiser, but supports
544complex data structures (similar to JSON) and is faster than any of the
545other serialisers. If you have the L<CBOR::XS> module available, it's the
546best choice.
547
548The encoder enables C<allow_sharing> (so this serialisation method can
549encode cyclic and self-referencing data structures).
550
551Implementation:
552
553 use CBOR::XS ();
554 (
555 sub { CBOR::XS::encode_cbor_sharing \@_ },
556 sub { @{ CBOR::XS::decode_cbor shift } }
557 )
558
559=item C<$AnyEvent::Fork::RPC::JSON_SERIALISER> - uses L<JSON::XS> or L<JSON>
531 560
532This serialiser creates JSON arrays - you have to make sure the L<JSON> 561This serialiser creates JSON arrays - you have to make sure the L<JSON>
533module is installed for this serialiser to work. It can be beneficial for 562module is installed for this serialiser to work. It can be beneficial for
534sharing when you preload the L<JSON> module in a template process. 563sharing when you preload the L<JSON> module in a template process.
535 564
… …
543 ( 572 (
544 sub { JSON::encode_json \@_ }, 573 sub { JSON::encode_json \@_ },
545 sub { @{ JSON::decode_json shift } } 574 sub { @{ JSON::decode_json shift } }
546 ) 575 )
547 576
548=item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER> 577=item C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER> - L<Storable>
549 578
550This serialiser uses L<Storable>, which means it has high chance of 579This serialiser uses L<Storable>, which means it has high chance of
551serialising just about anything you throw at it, at the cost of having 580serialising just about anything you throw at it, at the cost of having
552very high overhead per operation. It also comes with perl. It should be 581very high overhead per operation. It also comes with perl. It should be
553used when you need to serialise complex data structures. 582used when you need to serialise complex data structures.
… …
558 ( 587 (
559 sub { Storable::freeze \@_ }, 588 sub { Storable::freeze \@_ },
560 sub { @{ Storable::thaw shift } } 589 sub { @{ Storable::thaw shift } }
561 ) 590 )
562 591
563=item portable storable - C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER> 592=item C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER> - portable Storable
564 593
565This serialiser also uses L<Storable>, but uses it's "network" format 594This serialiser also uses L<Storable>, but uses it's "network" format
566to serialise data, which makes it possible to talk to different 595to serialise data, which makes it possible to talk to different
567perl binaries (for example, when talking to a process created with 596perl binaries (for example, when talking to a process created with
568L<AnyEvent::Fork::Remote>). 597L<AnyEvent::Fork::Remote>).
… …
583examples. 612examples.
584 613
585=cut 614=cut
586 615
587our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 616our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
617our $CBOR_XS_SERIALISER = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor_sharing \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
588our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })'; 618our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })';
589our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })'; 619our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
590our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })'; 620our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })';
591 621
592sub run { 622sub run {
593 my ($self, $function, %arg) = @_; 623 my ($self, $function, %arg) = @_;
… …
629 }; 659 };
630 660
631 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); 661 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync");
632 662
633 $self->require ($module) 663 $self->require ($module)
634 ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "CORE::exit") 664 ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "$module\::do_exit")
635 ->run ("$module\::run", sub { 665 ->run ("$module\::run", sub {
636 $fh = shift; 666 $fh = shift
667 or return $on_error->("connection failed");
637 668
638 my ($id, $len); 669 my ($id, $len);
639 $rw = AE::io $fh, 0, sub { 670 $rw = AE::io $fh, 0, sub {
640 $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf; 671 $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf;
641 $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf; 672 $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf;
… …
753values. 784values.
754 785
755See the examples section earlier in this document for some actual 786See the examples section earlier in this document for some actual
756examples. 787examples.
757 788
789Note: the event data, like any data send to the parent, might not be sent
790immediatelly but queued for later sending, so there is no guarantee that
791the event has been sent to the parent when the call returns - when you
792e.g. exit directly after calling this function, the parent might never
793receive the event.
794
758=back 795=back
759 796
760=head2 PROCESS EXIT 797=head2 PROCESS EXIT
761 798
762If and when the child process exits depends on the backend and 799If and when the child process exits depends on the backend and
… …
786 823
787For the asynchronous backend, things are more complicated: Whenever it 824For the asynchronous backend, things are more complicated: Whenever it
788listens for another request by the parent, it might detect that the socket 825listens for another request by the parent, it might detect that the socket
789was closed (e.g. because the parent exited). It will sotp listening for 826was closed (e.g. because the parent exited). It will sotp listening for
790new requests and instead try to write out any remaining data (if any) or 827new requests and instead try to write out any remaining data (if any) or
791simply check whether the socket cna be written to. After this, the RPC 828simply check whether the socket can be written to. After this, the RPC
792process is effectively done - no new requests are incoming, no outstanding 829process is effectively done - no new requests are incoming, no outstanding
793request data can be written back. 830request data can be written back.
794 831
795Since chances are high that there are event watchers that the RPC server 832Since chances are high that there are event watchers that the RPC server
796knows nothing about (why else would one use the async backend if not for 833knows nothing about (why else would one use the async backend if not for
797the ability to register watchers?), the event loop would often happily 834the ability to register watchers?), the event loop would often happily
798continue. 835continue.
799 836
800This is why the asynchronous backend explicitly calls C<CORE::exit> when 837This is why the asynchronous backend explicitly calls C<CORE::exit> when
801it is done (it will raise an exception under other circumstances, which 838it is done (under other circumstances, such as when there is an I/O error
802might lead to the process not exiting on it's own). 839and there is outstanding data to write, it will log a fatal message via
840L<AnyEvent::Log>, also causing the program to exit).
803 841
804You can override this by specifying a function name to call via the C<done> 842You can override this by specifying a function name to call via the C<done>
805parameter instead. 843parameter instead.
806 844
807=back 845=back
… …
866are queued and the jobs are slow, they will all run concurrently. The 904are queued and the jobs are slow, they will all run concurrently. The
867child must implement some queueing/limiting mechanism if this causes 905child must implement some queueing/limiting mechanism if this causes
868problems. Alternatively, the parent could limit the amount of rpc calls 906problems. Alternatively, the parent could limit the amount of rpc calls
869that are outstanding. 907that are outstanding.
870 908
871Blocking use of condvars is not supported. 909Blocking use of condvars is not supported (in the main thread, outside of
910e.g. L<Coro> threads).
872 911
873Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is 912Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
874easy. 913easy.
875 914
876=back 915=back
… …
942gory details. 981gory details.
943 982
944=head1 EXCEPTIONS 983=head1 EXCEPTIONS
945 984
946There are no provisions whatsoever for catching exceptions at this time - 985There are no provisions whatsoever for catching exceptions at this time -
947in the child, exeptions might kill the process, causing calls to be lost 986in the child, exceptions might kill the process, causing calls to be lost
948and the parent encountering a fatal error. In the parent, exceptions in 987and the parent encountering a fatal error. In the parent, exceptions in
949the result callback will not be caught and cause undefined behaviour. 988the result callback will not be caught and cause undefined behaviour.
950 989
951=head1 SEE ALSO 990=head1 SEE ALSO
952 991

Diff Legend

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