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.37 by root, Thu May 12 16:43:08 2016 UTC vs.
Revision 1.46 by root, Sun Sep 15 20:18:14 2019 UTC

… …
371 371
372There is an important twist - the C<AnyEvent::Fork::RPC::event> function 372There is an important twist - the C<AnyEvent::Fork::RPC::event> function
373is only defined when the child is fully initialised. If you redirect the 373is only defined when the child is fully initialised. If you redirect the
374log messages in your C<init> function for example, then the C<event> 374log messages in your C<init> function for example, then the C<event>
375function might not yet be available. This is why the log callback checks 375function might not yet be available. This is why the log callback checks
376whether the fucntion is there using C<defined>, and only then uses it to 376whether the function is there using C<defined>, and only then uses it to
377log the message. 377log the message.
378 378
379=head1 PARENT PROCESS USAGE 379=head1 PARENT PROCESS USAGE
380 380
381This module exports nothing, and only implements a single function: 381This module exports nothing, and only implements a single function:
… …
391use Errno (); 391use Errno ();
392use Guard (); 392use Guard ();
393 393
394use AnyEvent; 394use AnyEvent;
395 395
396our $VERSION = 1.21; 396our $VERSION = '2.0';
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:
… …
439been successfully handled. This is useful when you queue some requests and 439been successfully handled. This is useful when you queue some requests and
440want the child to go away after it has handled them. The problem is that 440want the child to go away after it has handled them. The problem is that
441the parent must not exit either until all requests have been handled, and 441the parent must not exit either until all requests have been handled, and
442this can be accomplished by waiting for this callback. 442this can be accomplished by waiting for this callback.
443 443
444=item init => $function (default none) 444=item init => $function (default: none)
445 445
446When specified (by name), this function is called in the child as the very 446When specified (by name), this function is called in the child as the very
447first thing when taking over the process, with all the arguments normally 447first thing when taking over the process, with all the arguments normally
448passed to the C<AnyEvent::Fork::run> function, except the communications 448passed to the C<AnyEvent::Fork::run> function, except the communications
449socket. 449socket.
… …
454It is called very early - before the serialisers are created or the 454It is called very early - before the serialisers are created or the
455C<$function> name is resolved into a function reference, so it could be 455C<$function> name is resolved into a function reference, so it could be
456used to load any modules that provide the serialiser or function. It can 456used to load any modules that provide the serialiser or function. It can
457not, however, create events. 457not, however, create events.
458 458
459=item done => $function (default C<CORE::exit>) 459=item done => $function (default: C<CORE::exit>)
460 460
461The function to call when the asynchronous backend detects an end of file 461The function to call when the asynchronous backend detects an end of file
462condition when reading from the communications socket I<and> there are no 462condition when reading from the communications socket I<and> there are no
463outstanding requests. It's ignored by the synchronous backend. 463outstanding requests. It is 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::run> 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: C<0>)
474 474
475The default server used in the child does all I/O blockingly, and only 475The default server used in the child does all I/O blockingly, and only
476allows a single RPC call to execute concurrently. 476allows a single RPC call to execute concurrently.
477 477
478Setting C<async> to a true value switches to another implementation that 478Setting C<async> to a true value switches to another implementation that
… …
488synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode. 488synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode.
489 489
490If you use a template process and want to fork both sync and async 490If you use a template process and want to fork both sync and async
491children, then it is permissible to load both modules. 491children, then it is permissible to load both modules.
492 492
493=item serialiser => $string (default: $AnyEvent::Fork::RPC::STRING_SERIALISER) 493=item serialiser => $string (default: C<$AnyEvent::Fork::RPC::STRING_SERIALISER>)
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
… …
509 509
510If you need an external module for serialisation, then you can either 510If you need an external module for serialisation, then you can either
511pre-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>
512or C<require> statement into the serialiser string. Or both. 512or C<require> statement into the serialiser string. Or both.
513 513
514Here are some examples - some of them are also available as global 514Here are some examples - all of them are also available as global
515variables that make them easier to use. 515variables that make them easier to use.
516 516
517=over 4 517=over 4
518 518
519=item C<$AnyEvent::Fork::RPC::STRING_SERIALISER> - octet strings only 519=item C<$AnyEvent::Fork::RPC::STRING_SERIALISER> - octet strings only
… …
603 sub { Storable::nfreeze \@_ }, 603 sub { Storable::nfreeze \@_ },
604 sub { @{ Storable::thaw shift } } 604 sub { @{ Storable::thaw shift } }
605 ) 605 )
606 606
607=back 607=back
608
609=item buflen => $bytes (default: C<512 - 16>)
610
611The starting size of the read buffer for request and response data.
612
613C<AnyEvent::Fork::RPC> ensures that the buffer for reeading request and
614response data is large enough for at leats aingle request or response, and
615will dynamically enlarge the buffer if needed.
616
617While this ensures that memory is not overly wasted, it typically leads
618to having to do one syscall per request, which can be inefficient in some
619cases. In such cases, it can be beneficient to increase the buffer size to
620hold more than one request.
621
622=item buflen_req => $bytes (default: same as C<buflen>)
623
624Overrides C<buflen> for request data (as read by the forked process).
625
626=item buflen_res => $bytes (default: same as C<buflen>)
627
628Overrides C<buflen> for response data (replies read by the parent process).
608 629
609=back 630=back
610 631
611See the examples section earlier in this document for some actual 632See the examples section earlier in this document for some actual
612examples. 633examples.
… …
636 $on_event ||= sub { $on_error->("event received, but no on_event handler") }; 657 $on_event ||= sub { $on_error->("event received, but no on_event handler") };
637 658
638 my ($f, $t) = eval $serialiser; die $@ if $@; 659 my ($f, $t) = eval $serialiser; die $@ if $@;
639 660
640 my (@rcb, %rcb, $fh, $shutdown, $wbuf, $ww); 661 my (@rcb, %rcb, $fh, $shutdown, $wbuf, $ww);
641 my ($rlen, $rbuf, $rw) = 512 - 16; 662 my ($rlen, $rbuf, $rw) = $arg{buflen_res} || $arg{buflen} || 512 - 16;
642 663
643 my $wcb = sub { 664 my $wcb = sub {
644 my $len = syswrite $fh, $wbuf; 665 my $len = syswrite $fh, $wbuf;
645 666
646 unless (defined $len) { 667 unless (defined $len) {
… …
658 } 679 }
659 }; 680 };
660 681
661 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync"); 682 my $module = "AnyEvent::Fork::RPC::" . ($arg{async} ? "Async" : "Sync");
662 683
663 $self->require ($module) 684 $self->eval ("use $module 2 ()")
664 ->send_arg ($function, $arg{init}, $serialiser, $arg{done} || "$module\::do_exit") 685 ->send_arg (
686 function => $function,
687 init => $arg{init},
688 serialiser => $serialiser,
689 done => $arg{done} || "$module\::do_exit",
690 rlen => $arg{buflen_req} || $arg{buflen} || 512 - 16,
691 -10 # the above are 10 arguments
692 )
665 ->run ("$module\::run", sub { 693 ->run ("$module\::run", sub {
666 $fh = shift; 694 $fh = shift
695 or return $on_error->("connection failed");
667 696
668 my ($id, $len); 697 my ($id, $len);
669 $rw = AE::io $fh, 0, sub { 698 $rw = AE::io $fh, 0, sub {
670 $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf; 699 $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf;
671 $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf; 700 $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf;
… …
772The following function is not available in this module. They are only 801The following function is not available in this module. They are only
773available in the namespace of this module when the child is running, 802available in the namespace of this module when the child is running,
774without having to load any extra modules. They are part of the child-side 803without having to load any extra modules. They are part of the child-side
775API of L<AnyEvent::Fork::RPC>. 804API of L<AnyEvent::Fork::RPC>.
776 805
806Note that these functions are typically not yet declared when code is
807compiled into the child, because the backend module is only loaded when
808you call C<run>, which is typically the last method you call on the fork
809object.
810
811Therefore, you either have to explicitly pre-load the right backend module
812or mark calls to these functions as function calls, e.g.:
813
814 AnyEvent::Fork::RPC::event (0 => "five");
815 AnyEvent::Fork::RPC::event->(0 => "five");
816 &AnyEvent::Fork::RPC::flush;
817
777=over 4 818=over 4
778 819
779=item AnyEvent::Fork::RPC::event ... 820=item AnyEvent::Fork::RPC::event (...)
780 821
781Send an event to the parent. Events are a bit like RPC calls made by the 822Send an event to the parent. Events are a bit like RPC calls made by the
782child process to the parent, except that there is no notion of return 823child process to the parent, except that there is no notion of return
783values. 824values.
784 825
785See the examples section earlier in this document for some actual 826See the examples section earlier in this document for some actual
786examples. 827examples.
828
829Note: the event data, like any data send to the parent, might not be sent
830immediatelly but queued for later sending, so there is no guarantee that
831the event has been sent to the parent when the call returns - when you
832e.g. exit directly after calling this function, the parent might never
833receive the event. See the next function for a remedy.
834
835=item $success = AnyEvent::Fork::RPC::flush ()
836
837Synchronously wait and flush the reply data to the parent. Returns true on
838success and false otherwise (i.e. when the reply data cannot be written at
839all). Ignoring the success status is a common and healthy behaviour.
840
841Only the "async" backend does something on C<flush> - the "sync" backend
842is not buffering reply data and always returns true from this function.
843
844Normally, reply data might or might not be written to the parent
845immediatelly but is buffered. This can greatly improve performance and
846efficiency, but sometimes can get in your way: for example. when you want
847to send an error message just before exiting, or when you want to ensure
848replies timely reach the parent before starting a long blocking operation.
849
850In these cases, you can call this function to flush any outstanding reply
851data to the parent. This is done blockingly, so no requests will be
852handled and no event callbacks will be called.
853
854For example, you could wrap your request function in a C<eval> block and
855report the exception string back to the caller just before exiting:
856
857 sub req {
858 ...
859
860 eval {
861 ...
862 };
863
864 if ($@) {
865 AnyEvent::RPC::event (throw => "$@");
866 AnyEvent::RPC::flush ();
867 exit;
868 }
869
870 ...
871 }
787 872
788=back 873=back
789 874
790=head2 PROCESS EXIT 875=head2 PROCESS EXIT
791 876

Diff Legend

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