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.35 by root, Wed Nov 20 16:17:22 2013 UTC vs.
Revision 1.37 by root, Thu May 12 16:43:08 2016 UTC

… …
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
… …
512Here are some examples - some of them are also available as global 514Here are some examples - some 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::CBOR_XS_SERIALISER> 536=item C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER> - uses L<CBOR::XS>
531 537
532This serialiser creates CBOR::XS arrays - you have to make sure the 538This 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 539L<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 540beneficial for sharing when you preload the L<CBOR::XS> module in a template
535process. 541process.
… …
537L<CBOR::XS> is about as fast as the octet string serialiser, but supports 543L<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 544complex 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 545other serialisers. If you have the L<CBOR::XS> module available, it's the
540best choice. 546best choice.
541 547
542Note that the CBOR::XS module supports some extensions to encode cyclic 548The encoder enables C<allow_sharing> (so this serialisation method can
543and self-referencing data structures, which are not enabled. You need to 549encode cyclic and self-referencing data structures).
544write your own serialiser to take advantage of these.
545 550
546Implementation: 551Implementation:
547 552
548 use CBOR::XS (); 553 use CBOR::XS ();
549 ( 554 (
550 sub { CBOR::XS::encode_cbor \@_ }, 555 sub { CBOR::XS::encode_cbor_sharing \@_ },
551 sub { @{ CBOR::XS::decode_cbor shift } } 556 sub { @{ CBOR::XS::decode_cbor shift } }
552 ) 557 )
553 558
554=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER> 559=item C<$AnyEvent::Fork::RPC::JSON_SERIALISER> - uses L<JSON::XS> or L<JSON>
555 560
556This 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>
557module 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
558sharing when you preload the L<JSON> module in a template process. 563sharing when you preload the L<JSON> module in a template process.
559 564
… …
567 ( 572 (
568 sub { JSON::encode_json \@_ }, 573 sub { JSON::encode_json \@_ },
569 sub { @{ JSON::decode_json shift } } 574 sub { @{ JSON::decode_json shift } }
570 ) 575 )
571 576
572=item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER> 577=item C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER> - L<Storable>
573 578
574This serialiser uses L<Storable>, which means it has high chance of 579This serialiser uses L<Storable>, which means it has high chance of
575serialising 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
576very 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
577used when you need to serialise complex data structures. 582used when you need to serialise complex data structures.
… …
582 ( 587 (
583 sub { Storable::freeze \@_ }, 588 sub { Storable::freeze \@_ },
584 sub { @{ Storable::thaw shift } } 589 sub { @{ Storable::thaw shift } }
585 ) 590 )
586 591
587=item portable storable - C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER> 592=item C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER> - portable Storable
588 593
589This serialiser also uses L<Storable>, but uses it's "network" format 594This serialiser also uses L<Storable>, but uses it's "network" format
590to serialise data, which makes it possible to talk to different 595to serialise data, which makes it possible to talk to different
591perl binaries (for example, when talking to a process created with 596perl binaries (for example, when talking to a process created with
592L<AnyEvent::Fork::Remote>). 597L<AnyEvent::Fork::Remote>).
… …
607examples. 612examples.
608 613
609=cut 614=cut
610 615
611our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 616our $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 } })'; 617our $CBOR_XS_SERIALISER = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor_sharing \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
613our $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 } })';
614our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })'; 619our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
615our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })'; 620our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })';
616 621
617sub run { 622sub run {
618 my ($self, $function, %arg) = @_; 623 my ($self, $function, %arg) = @_;
… …
892are queued and the jobs are slow, they will all run concurrently. The 897are queued and the jobs are slow, they will all run concurrently. The
893child must implement some queueing/limiting mechanism if this causes 898child must implement some queueing/limiting mechanism if this causes
894problems. Alternatively, the parent could limit the amount of rpc calls 899problems. Alternatively, the parent could limit the amount of rpc calls
895that are outstanding. 900that are outstanding.
896 901
897Blocking use of condvars is not supported. 902Blocking use of condvars is not supported (in the main thread, outside of
903e.g. L<Coro> threads).
898 904
899Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is 905Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
900easy. 906easy.
901 907
902=back 908=back
… …
968gory details. 974gory details.
969 975
970=head1 EXCEPTIONS 976=head1 EXCEPTIONS
971 977
972There are no provisions whatsoever for catching exceptions at this time - 978There are no provisions whatsoever for catching exceptions at this time -
973in the child, exeptions might kill the process, causing calls to be lost 979in the child, exceptions might kill the process, causing calls to be lost
974and the parent encountering a fatal error. In the parent, exceptions in 980and the parent encountering a fatal error. In the parent, exceptions in
975the result callback will not be caught and cause undefined behaviour. 981the result callback will not be caught and cause undefined behaviour.
976 982
977=head1 SEE ALSO 983=head1 SEE ALSO
978 984

Diff Legend

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