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.34 by root, Wed Nov 20 15:26:56 2013 UTC vs.
Revision 1.40 by root, Sat May 21 07:11:09 2016 UTC

… …
391use Errno (); 391use Errno ();
392use Guard (); 392use Guard ();
393 393
394use AnyEvent; 394use AnyEvent;
395 395
396our $VERSION = 1.21; 396our $VERSION = 1.22;
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) = @_;
… …
753values. 783values.
754 784
755See the examples section earlier in this document for some actual 785See the examples section earlier in this document for some actual
756examples. 786examples.
757 787
788Note: the event data, like any data send to the parent, might not be sent
789immediatelly but queued for later sending, so there is no guarantee that
790the event has been sent to the parent when the call returns - when you
791e.g. exit directly after calling this function, the parent might never
792receive the event.
793
758=back 794=back
759 795
760=head2 PROCESS EXIT 796=head2 PROCESS EXIT
761 797
762If and when the child process exits depends on the backend and 798If and when the child process exits depends on the backend and
… …
867are queued and the jobs are slow, they will all run concurrently. The 903are queued and the jobs are slow, they will all run concurrently. The
868child must implement some queueing/limiting mechanism if this causes 904child must implement some queueing/limiting mechanism if this causes
869problems. Alternatively, the parent could limit the amount of rpc calls 905problems. Alternatively, the parent could limit the amount of rpc calls
870that are outstanding. 906that are outstanding.
871 907
872Blocking use of condvars is not supported. 908Blocking use of condvars is not supported (in the main thread, outside of
909e.g. L<Coro> threads).
873 910
874Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is 911Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
875easy. 912easy.
876 913
877=back 914=back
… …
943gory details. 980gory details.
944 981
945=head1 EXCEPTIONS 982=head1 EXCEPTIONS
946 983
947There are no provisions whatsoever for catching exceptions at this time - 984There are no provisions whatsoever for catching exceptions at this time -
948in the child, exeptions might kill the process, causing calls to be lost 985in the child, exceptions might kill the process, causing calls to be lost
949and the parent encountering a fatal error. In the parent, exceptions in 986and the parent encountering a fatal error. In the parent, exceptions in
950the result callback will not be caught and cause undefined behaviour. 987the result callback will not be caught and cause undefined behaviour.
951 988
952=head1 SEE ALSO 989=head1 SEE ALSO
953 990

Diff Legend

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