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.13 by root, Thu Apr 18 11:11:26 2013 UTC vs.
Revision 1.19 by root, Thu Apr 18 20:27:02 2013 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork 3AnyEvent::Fork::RPC - simple RPC extension for AnyEvent::Fork
4
5THE API IS NOT FINISHED, CONSIDER THIS A TECHNOLOGY DEMO
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7 use AnyEvent::Fork::RPC; 9 use AnyEvent::Fork::RPC;
8 # use AnyEvent::Fork is not needed 10 # use AnyEvent::Fork is not needed
… …
11 ->new 13 ->new
12 ->require ("MyModule") 14 ->require ("MyModule")
13 ->AnyEvent::Fork::RPC::run ( 15 ->AnyEvent::Fork::RPC::run (
14 "MyModule::server", 16 "MyModule::server",
15 ); 17 );
18
19 use AnyEvent;
16 20
17 my $cv = AE::cv; 21 my $cv = AE::cv;
18 22
19 $rpc->(1, 2, 3, sub { 23 $rpc->(1, 2, 3, sub {
20 print "MyModule::server returned @_\n"; 24 print "MyModule::server returned @_\n";
… …
372 376
373The default server used in the child does all I/O blockingly, and only 377The default server used in the child does all I/O blockingly, and only
374allows a single RPC call to execute concurrently. 378allows a single RPC call to execute concurrently.
375 379
376Setting C<async> to a true value switches to another implementation that 380Setting C<async> to a true value switches to another implementation that
377uses L<AnyEvent> in the child and allows multiple concurrent RPC calls. 381uses L<AnyEvent> in the child and allows multiple concurrent RPC calls (it
382does not support recursion in the event loop however, blocking condvar
383calls will fail).
378 384
379The actual API in the child is documented in the section that describes 385The actual API in the child is documented in the section that describes
380the calling semantics of the returned C<$rpc> function. 386the calling semantics of the returned C<$rpc> function.
381 387
382If you want to pre-load the actual back-end modules to enable memory 388If you want to pre-load the actual back-end modules to enable memory
… …
384synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode. 390synchronous, and C<AnyEvent::Fork::RPC::Async> for asynchronous mode.
385 391
386If you use a template process and want to fork both sync and async 392If you use a template process and want to fork both sync and async
387children, then it is permissible to load both modules. 393children, then it is permissible to load both modules.
388 394
389=item serialiser => $string (default: '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })') 395=item serialiser => $string (default: $AnyEvent::Fork::RPC::STRING_SERIALISER)
390 396
391All arguments, result data and event data have to be serialised to be 397All arguments, result data and event data have to be serialised to be
392transferred between the processes. For this, they have to be frozen and 398transferred between the processes. For this, they have to be frozen and
393thawed in both parent and child processes. 399thawed in both parent and child processes.
394 400
395By default, only octet strings can be passed between the processes, which 401By default, only octet strings can be passed between the processes, which
396is reasonably fast and efficient. 402is reasonably fast and efficient and requires no extra modules.
397 403
398For more complicated use cases, you can provide your own freeze and thaw 404For more complicated use cases, you can provide your own freeze and thaw
399functions, by specifying a string with perl source code. It's supposed to 405functions, by specifying a string with perl source code. It's supposed to
400return two code references when evaluated: the first receives a list of 406return two code references when evaluated: the first receives a list of
401perl values and must return an octet string. The second receives the octet 407perl values and must return an octet string. The second receives the octet
… …
403 409
404If you need an external module for serialisation, then you can either 410If you need an external module for serialisation, then you can either
405pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use> 411pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use>
406or C<require> statement into the serialiser string. Or both. 412or C<require> statement into the serialiser string. Or both.
407 413
414Here are some examples - some of them are also available as global
415variables that make them easier to use.
416
417=over 4
418
419=item octet strings - C<$AnyEvent::Fork::RPC::STRING_SERIALISER>
420
421This serialiser concatenates length-prefixes octet strings, and is the
422default.
423
424Implementation:
425
426 (
427 sub { pack "(w/a*)*", @_ },
428 sub { unpack "(w/a*)*", shift }
429 )
430
431=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER>
432
433This serialiser creates JSON arrays - you have to make sure the L<JSON>
434module is installed for this serialiser to work. It can be beneficial for
435sharing when you preload the L<JSON> module in a template process.
436
437L<JSON> (with L<JSON::XS> installed) is slower than the octet string
438serialiser, but usually much faster than L<Storable>, unless big chunks of
439binary data need to be transferred.
440
441Implementation:
442
443 use JSON ();
444 (
445 sub { JSON::encode_json \@_ },
446 sub { @{ JSON::decode_json shift } }
447 )
448
449=item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER>
450
451This serialiser uses L<Storable>, which means it has high chance of
452serialising just about anything you throw at it, at the cost of having
453very high overhead per operation. It also comes with perl.
454
455Implementation:
456
457 use Storable ();
458 (
459 sub { Storable::freeze \@_ },
460 sub { @{ Storable::thaw shift } }
461 )
462
463=back
464
408=back 465=back
409 466
410See the examples section earlier in this document for some actual 467See the examples section earlier in this document for some actual
411examples. 468examples.
412 469
413=cut 470=cut
414 471
415our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })'; 472our $STRING_SERIALISER = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
473our $JSON_SERIALISER = 'use JSON (); (sub { JSON::encode_json \@_ }, sub { @{ JSON::decode_json shift } })';
474our $STORABLE_SERIALISER = 'use Storable (); (sub { Storable::freeze \@_ }, sub { @{ Storable::thaw shift } })';
416 475
417sub run { 476sub run {
418 my ($self, $function, %arg) = @_; 477 my ($self, $function, %arg) = @_;
419 478
420 my $serialiser = delete $arg{serialiser} || $STRING_SERIALISER; 479 my $serialiser = delete $arg{serialiser} || $STRING_SERIALISER;
… …
504 $ww ||= AE::io $fh, 1, $wcb; 563 $ww ||= AE::io $fh, 1, $wcb;
505 }); 564 });
506 565
507 my $guard = Guard::guard { 566 my $guard = Guard::guard {
508 $shutdown = 1; 567 $shutdown = 1;
509 $ww ||= $fh && AE::io $fh, 1, $wcb; 568
569 shutdown $fh, 1 if $fh && !$ww;
510 }; 570 };
511 571
512 my $id; 572 my $id;
513 573
514 $arg{async} 574 $arg{async}
… …
640are queued and the jobs are slow, they will all run concurrently. The 700are queued and the jobs are slow, they will all run concurrently. The
641child must implement some queueing/limiting mechanism if this causes 701child must implement some queueing/limiting mechanism if this causes
642problems. Alternatively, the parent could limit the amount of rpc calls 702problems. Alternatively, the parent could limit the amount of rpc calls
643that are outstanding. 703that are outstanding.
644 704
705Blocking use of condvars is not supported.
706
645Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is 707Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
646easy. 708easy.
647 709
648=back 710=back
649 711
… …
712so you might want to look into L<AnyEvent::FDpasser> which can handle the 774so you might want to look into L<AnyEvent::FDpasser> which can handle the
713gory details. 775gory details.
714 776
715=head1 SEE ALSO 777=head1 SEE ALSO
716 778
717L<AnyEvent::Fork> (to create the processes in the first place), 779L<AnyEvent::Fork>, to create the processes in the first place.
780
718L<AnyEvent::Fork::Pool> (to manage whole pools of processes). 781L<AnyEvent::Fork::Pool>, to manage whole pools of processes.
719 782
720=head1 AUTHOR AND CONTACT INFORMATION 783=head1 AUTHOR AND CONTACT INFORMATION
721 784
722 Marc Lehmann <schmorp@schmorp.de> 785 Marc Lehmann <schmorp@schmorp.de>
723 http://software.schmorp.de/pkg/AnyEvent-Fork-RPC 786 http://software.schmorp.de/pkg/AnyEvent-Fork-RPC

Diff Legend

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