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.38 by root, Thu May 12 16:53:13 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
… …
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) = @_;
… …
867are 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
868child must implement some queueing/limiting mechanism if this causes 898child must implement some queueing/limiting mechanism if this causes
869problems. Alternatively, the parent could limit the amount of rpc calls 899problems. Alternatively, the parent could limit the amount of rpc calls
870that are outstanding. 900that are outstanding.
871 901
872Blocking use of condvars is not supported. 902Blocking use of condvars is not supported (in the main thread, outside of
903e.g. L<Coro> threads).
873 904
874Using 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
875easy. 906easy.
876 907
877=back 908=back
… …
943gory details. 974gory details.
944 975
945=head1 EXCEPTIONS 976=head1 EXCEPTIONS
946 977
947There are no provisions whatsoever for catching exceptions at this time - 978There are no provisions whatsoever for catching exceptions at this time -
948in 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
949and the parent encountering a fatal error. In the parent, exceptions in 980and the parent encountering a fatal error. In the parent, exceptions in
950the result callback will not be caught and cause undefined behaviour. 981the result callback will not be caught and cause undefined behaviour.
951 982
952=head1 SEE ALSO 983=head1 SEE ALSO
953 984

Diff Legend

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