| … | |
… | |
| 2 | |
2 | |
| 3 | AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork |
3 | AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork |
| 4 | |
4 | |
| 5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
| 6 | |
6 | |
|
|
7 | use AnyEvent::Fork; |
| 7 | use AnyEvent::Fork::RPC; |
8 | use AnyEvent::Fork::RPC; |
| 8 | # use AnyEvent::Fork is not needed |
|
|
| 9 | |
9 | |
| 10 | my $rpc = AnyEvent::Fork |
10 | my $rpc = AnyEvent::Fork |
| 11 | ->new |
11 | ->new |
| 12 | ->require ("MyModule") |
12 | ->require ("MyModule") |
| 13 | ->AnyEvent::Fork::RPC::run ( |
13 | ->AnyEvent::Fork::RPC::run ( |
| 14 | "MyModule::server", |
14 | "MyModule::server", |
| 15 | ); |
15 | ); |
| 16 | |
16 | |
|
|
17 | use AnyEvent; |
|
|
18 | |
| 17 | my $cv = AE::cv; |
19 | my $cv = AE::cv; |
| 18 | |
20 | |
| 19 | $rpc->(1, 2, 3, sub { |
21 | $rpc->(1, 2, 3, sub { |
| 20 | print "MyModule::server returned @_\n"; |
22 | print "MyModule::server returned @_\n"; |
| 21 | $cv->send; |
23 | $cv->send; |
| … | |
… | |
| 24 | $cv->recv; |
26 | $cv->recv; |
| 25 | |
27 | |
| 26 | =head1 DESCRIPTION |
28 | =head1 DESCRIPTION |
| 27 | |
29 | |
| 28 | This module implements a simple RPC protocol and backend for processes |
30 | This module implements a simple RPC protocol and backend for processes |
| 29 | created via L<AnyEvent::Fork>, allowing you to call a function in the |
31 | created via L<AnyEvent::Fork> (or L<AnyEvent::Fork::Remote>), allowing you |
| 30 | child process and receive its return values (up to 4GB serialised). |
32 | to call a function in the child process and receive its return values (up |
|
|
33 | to 4GB serialised). |
| 31 | |
34 | |
| 32 | It implements two different backends: a synchronous one that works like a |
35 | It implements two different backends: a synchronous one that works like a |
| 33 | normal function call, and an asynchronous one that can run multiple jobs |
36 | normal function call, and an asynchronous one that can run multiple jobs |
| 34 | concurrently in the child, using AnyEvent. |
37 | concurrently in the child, using AnyEvent. |
| 35 | |
38 | |
| 36 | It also implements an asynchronous event mechanism from the child to the |
39 | It also implements an asynchronous event mechanism from the child to the |
| 37 | parent, that could be used for progress indications or other information. |
40 | parent, that could be used for progress indications or other information. |
| 38 | |
|
|
| 39 | Loading this module also always loads L<AnyEvent::Fork>, so you can make a |
|
|
| 40 | separate C<use AnyEvent::Fork> if you wish, but you don't have to. |
|
|
| 41 | |
41 | |
| 42 | =head1 EXAMPLES |
42 | =head1 EXAMPLES |
| 43 | |
43 | |
| 44 | =head2 Example 1: Synchronous Backend |
44 | =head2 Example 1: Synchronous Backend |
| 45 | |
45 | |
| … | |
… | |
| 49 | silly, but illustrates the use of events. |
49 | silly, but illustrates the use of events. |
| 50 | |
50 | |
| 51 | First the parent process: |
51 | First the parent process: |
| 52 | |
52 | |
| 53 | use AnyEvent; |
53 | use AnyEvent; |
|
|
54 | use AnyEvent::Fork; |
| 54 | use AnyEvent::Fork::RPC; |
55 | use AnyEvent::Fork::RPC; |
| 55 | |
56 | |
| 56 | my $done = AE::cv; |
57 | my $done = AE::cv; |
| 57 | |
58 | |
| 58 | my $rpc = AnyEvent::Fork |
59 | my $rpc = AnyEvent::Fork |
| … | |
… | |
| 189 | so silly anymore. |
190 | so silly anymore. |
| 190 | |
191 | |
| 191 | Without further ado, here is the code: |
192 | Without further ado, here is the code: |
| 192 | |
193 | |
| 193 | use AnyEvent; |
194 | use AnyEvent; |
|
|
195 | use AnyEvent::Fork; |
| 194 | use AnyEvent::Fork::RPC; |
196 | use AnyEvent::Fork::RPC; |
| 195 | |
197 | |
| 196 | my $done = AE::cv; |
198 | my $done = AE::cv; |
| 197 | |
199 | |
| 198 | my $rpc = AnyEvent::Fork |
200 | my $rpc = AnyEvent::Fork |
| … | |
… | |
| 301 | |
303 | |
| 302 | use Errno (); |
304 | use Errno (); |
| 303 | use Guard (); |
305 | use Guard (); |
| 304 | |
306 | |
| 305 | use AnyEvent; |
307 | use AnyEvent; |
| 306 | use AnyEvent::Fork; # we don't actually depend on it, this is for convenience |
|
|
| 307 | |
308 | |
| 308 | our $VERSION = 0.1; |
309 | our $VERSION = 1.1; |
| 309 | |
310 | |
| 310 | =item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...] |
311 | =item my $rpc = AnyEvent::Fork::RPC::run $fork, $function, [key => value...] |
| 311 | |
312 | |
| 312 | The traditional way to call it. But it is way cooler to call it in the |
313 | The traditional way to call it. But it is way cooler to call it in the |
| 313 | following way: |
314 | following way: |
| … | |
… | |
| 372 | |
373 | |
| 373 | The default server used in the child does all I/O blockingly, and only |
374 | The default server used in the child does all I/O blockingly, and only |
| 374 | allows a single RPC call to execute concurrently. |
375 | allows a single RPC call to execute concurrently. |
| 375 | |
376 | |
| 376 | Setting C<async> to a true value switches to another implementation that |
377 | Setting C<async> to a true value switches to another implementation that |
| 377 | uses L<AnyEvent> in the child and allows multiple concurrent RPC calls. |
378 | uses L<AnyEvent> in the child and allows multiple concurrent RPC calls (it |
|
|
379 | does not support recursion in the event loop however, blocking condvar |
|
|
380 | calls will fail). |
| 378 | |
381 | |
| 379 | The actual API in the child is documented in the section that describes |
382 | The actual API in the child is documented in the section that describes |
| 380 | the calling semantics of the returned C<$rpc> function. |
383 | the calling semantics of the returned C<$rpc> function. |
| 381 | |
384 | |
| 382 | If you want to pre-load the actual back-end modules to enable memory |
385 | If you want to pre-load the actual back-end modules to enable memory |
| … | |
… | |
| 518 | $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf; |
521 | $rlen = $rlen * 2 + 16 if $rlen - 128 < length $rbuf; |
| 519 | $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf; |
522 | $len = sysread $fh, $rbuf, $rlen - length $rbuf, length $rbuf; |
| 520 | |
523 | |
| 521 | if ($len) { |
524 | if ($len) { |
| 522 | while (8 <= length $rbuf) { |
525 | while (8 <= length $rbuf) { |
| 523 | ($id, $len) = unpack "LL", $rbuf; |
526 | ($id, $len) = unpack "NN", $rbuf; |
| 524 | 8 + $len <= length $rbuf |
527 | 8 + $len <= length $rbuf |
| 525 | or last; |
528 | or last; |
| 526 | |
529 | |
| 527 | my @r = $t->(substr $rbuf, 8, $len); |
530 | my @r = $t->(substr $rbuf, 8, $len); |
| 528 | substr $rbuf, 0, 8 + $len, ""; |
531 | substr $rbuf, 0, 8 + $len, ""; |
| … | |
… | |
| 544 | undef $rw; undef $ww; # it ends here |
547 | undef $rw; undef $ww; # it ends here |
| 545 | |
548 | |
| 546 | if (@rcb || %rcb) { |
549 | if (@rcb || %rcb) { |
| 547 | $on_error->("unexpected eof"); |
550 | $on_error->("unexpected eof"); |
| 548 | } else { |
551 | } else { |
| 549 | $on_destroy->(); |
552 | $on_destroy->() |
|
|
553 | if $on_destroy; |
| 550 | } |
554 | } |
| 551 | } elsif ($! != Errno::EAGAIN && $! != Errno::EWOULDBLOCK) { |
555 | } elsif ($! != Errno::EAGAIN && $! != Errno::EWOULDBLOCK) { |
| 552 | undef $rw; undef $ww; # it ends here |
556 | undef $rw; undef $ww; # it ends here |
| 553 | $on_error->("read: $!"); |
557 | $on_error->("read: $!"); |
| 554 | } |
558 | } |
| … | |
… | |
| 557 | $ww ||= AE::io $fh, 1, $wcb; |
561 | $ww ||= AE::io $fh, 1, $wcb; |
| 558 | }); |
562 | }); |
| 559 | |
563 | |
| 560 | my $guard = Guard::guard { |
564 | my $guard = Guard::guard { |
| 561 | $shutdown = 1; |
565 | $shutdown = 1; |
| 562 | $ww ||= $fh && AE::io $fh, 1, $wcb; |
566 | |
|
|
567 | shutdown $fh, 1 if $fh && !$ww; |
| 563 | }; |
568 | }; |
| 564 | |
569 | |
| 565 | my $id; |
570 | my $id; |
| 566 | |
571 | |
| 567 | $arg{async} |
572 | $arg{async} |
| … | |
… | |
| 569 | $id = ($id == 0xffffffff ? 0 : $id) + 1; |
574 | $id = ($id == 0xffffffff ? 0 : $id) + 1; |
| 570 | $id = ($id == 0xffffffff ? 0 : $id) + 1 while exists $rcb{$id}; # rarely loops |
575 | $id = ($id == 0xffffffff ? 0 : $id) + 1 while exists $rcb{$id}; # rarely loops |
| 571 | |
576 | |
| 572 | $rcb{$id} = pop; |
577 | $rcb{$id} = pop; |
| 573 | |
578 | |
| 574 | $guard; # keep it alive |
579 | $guard if 0; # keep it alive |
| 575 | |
580 | |
| 576 | $wbuf .= pack "LL/a*", $id, &$f; |
581 | $wbuf .= pack "NN/a*", $id, &$f; |
| 577 | $ww ||= $fh && AE::io $fh, 1, $wcb; |
582 | $ww ||= $fh && AE::io $fh, 1, $wcb; |
| 578 | } |
583 | } |
| 579 | : sub { |
584 | : sub { |
| 580 | push @rcb, pop; |
585 | push @rcb, pop; |
| 581 | |
586 | |
| 582 | $guard; # keep it alive |
587 | $guard; # keep it alive |
| 583 | |
588 | |
| 584 | $wbuf .= pack "L/a*", &$f; |
589 | $wbuf .= pack "N/a*", &$f; |
| 585 | $ww ||= $fh && AE::io $fh, 1, $wcb; |
590 | $ww ||= $fh && AE::io $fh, 1, $wcb; |
| 586 | } |
591 | } |
| 587 | } |
592 | } |
| 588 | |
593 | |
| 589 | =item $rpc->(..., $cb->(...)) |
594 | =item $rpc->(..., $cb->(...)) |
| … | |
… | |
| 693 | are queued and the jobs are slow, they will all run concurrently. The |
698 | are queued and the jobs are slow, they will all run concurrently. The |
| 694 | child must implement some queueing/limiting mechanism if this causes |
699 | child must implement some queueing/limiting mechanism if this causes |
| 695 | problems. Alternatively, the parent could limit the amount of rpc calls |
700 | problems. Alternatively, the parent could limit the amount of rpc calls |
| 696 | that are outstanding. |
701 | that are outstanding. |
| 697 | |
702 | |
|
|
703 | Blocking use of condvars is not supported. |
|
|
704 | |
| 698 | Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is |
705 | Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is |
| 699 | easy. |
706 | easy. |
| 700 | |
707 | |
| 701 | =back |
708 | =back |
| 702 | |
709 | |
| … | |
… | |
| 718 | half it has passed earlier. |
725 | half it has passed earlier. |
| 719 | |
726 | |
| 720 | Here is some (untested) pseudocode to that effect: |
727 | Here is some (untested) pseudocode to that effect: |
| 721 | |
728 | |
| 722 | use AnyEvent::Util; |
729 | use AnyEvent::Util; |
|
|
730 | use AnyEvent::Fork; |
| 723 | use AnyEvent::Fork::RPC; |
731 | use AnyEvent::Fork::RPC; |
| 724 | use IO::FDPass; |
732 | use IO::FDPass; |
| 725 | |
733 | |
| 726 | my ($s1, $s2) = AnyEvent::Util::portable_socketpair; |
734 | my ($s1, $s2) = AnyEvent::Util::portable_socketpair; |
| 727 | |
735 | |
| … | |
… | |
| 763 | |
771 | |
| 764 | Of course, this might be blocking if you pass a lot of file descriptors, |
772 | Of course, this might be blocking if you pass a lot of file descriptors, |
| 765 | so you might want to look into L<AnyEvent::FDpasser> which can handle the |
773 | so you might want to look into L<AnyEvent::FDpasser> which can handle the |
| 766 | gory details. |
774 | gory details. |
| 767 | |
775 | |
|
|
776 | =head1 EXCEPTIONS |
|
|
777 | |
|
|
778 | There are no provisions whatsoever for catching exceptions at this time - |
|
|
779 | in the child, exeptions might kill the process, causing calls to be lost |
|
|
780 | and the parent encountering a fatal error. In the parent, exceptions in |
|
|
781 | the result callback will not be caught and cause undefined behaviour. |
|
|
782 | |
| 768 | =head1 SEE ALSO |
783 | =head1 SEE ALSO |
| 769 | |
784 | |
| 770 | L<AnyEvent::Fork> (to create the processes in the first place), |
785 | L<AnyEvent::Fork>, to create the processes in the first place. |
|
|
786 | |
|
|
787 | L<AnyEvent::Fork::Remote>, likewise, but helpful for remote processes. |
|
|
788 | |
| 771 | L<AnyEvent::Fork::Pool> (to manage whole pools of processes). |
789 | L<AnyEvent::Fork::Pool>, to manage whole pools of processes. |
| 772 | |
790 | |
| 773 | =head1 AUTHOR AND CONTACT INFORMATION |
791 | =head1 AUTHOR AND CONTACT INFORMATION |
| 774 | |
792 | |
| 775 | Marc Lehmann <schmorp@schmorp.de> |
793 | Marc Lehmann <schmorp@schmorp.de> |
| 776 | http://software.schmorp.de/pkg/AnyEvent-Fork-RPC |
794 | http://software.schmorp.de/pkg/AnyEvent-Fork-RPC |
