[ViewVC] Diff of: cvs/AnyEvent-Fork-RPC/RPC.pm

Comparing AnyEvent-Fork-RPC/RPC.pm (file contents):
Revision 1.28 by root, Sun Apr 28 15:48:31 2013 UTC vs.
Revision 1.29 by root, Sun Aug 25 21:52:15 2013 UTC

    $cv->recv;
 =head1 DESCRIPTION
 This module implements a simple RPC protocol and backend for processes
-created via L<AnyEvent::Fork> (or L<AnyEvent::Fork::Remote>), allowing you
+created via L<AnyEvent::Fork> or L<AnyEvent::Fork::Remote>, allowing you
 to call a function in the child process and receive its return values (up
 to 4GB serialised).
 It implements two different backends: a synchronous one that works like a
 normal function call, and an asynchronous one that can run multiple jobs
    my $rpc = AnyEvent::Fork
       ->new
       ->require ("MyWorker")
       ->AnyEvent::Fork::RPC::run ("MyWorker::run",
-         on_error   => sub { warn "FATAL: $_[0]"; exit 1 },
+         on_error   => sub { warn "ERROR: $_[0]"; exit 1 },
          on_event   => sub { warn "$_[0] requests handled\n" },
          on_destroy => $done,
       );
    for my $id (1..6) {
       ->new
       ->require ("AnyEvent::Fork::RPC::Async")
       ->eval (do { local $/; <DATA> })
       ->AnyEvent::Fork::RPC::run ("run",
          async      => 1,
-         on_error   => sub { warn "FATAL: $_[0]"; exit 1 },
+         on_error   => sub { warn "ERROR: $_[0]"; exit 1 },
          on_event   => sub { print $_[0] },
          on_destroy => $done,
       );
    for my $count (3, 2, 1) {
 This concludes the async example. Since L<AnyEvent::Fork> does not
 actually fork, you are free to use about any module in the child, not just
 L<AnyEvent>, but also L<IO::AIO>, or L<Tk> for example.
+=head2 Example 3: Asynchronous backend with Coro
+With L<Coro> you can create a nice asynchronous backend implementation by
+defining an rpc server function that creates a new Coro thread for every
+request that calls a function "normally", i.e. the parameters from the
+parent process are passed to it, and any return values are returned to the
+parent process, e.g.:
+   package My::Arith;
+   sub add {
+      return $_[0] + $_[1];
+   }
+   sub mul {
+      return $_[0] * $_[1];
+   }
+   sub run {
+      my ($done, $func, @arg) = @_;
+      Coro::async_pool {
+         $done->($func->(@arg));
+      };
+   }
+The C<run> function creates a new thread for every invocation, using the
+first argument as function name, and calls the C<$done> callback on it's
+return values. This makes it quite natural to define the C<add> and C<mul>
+functions to add or multiply two numbers and return the result.
+Since this is the asynchronous backend, it's quite possible to define RPC
+function that do I/O or wait for external events - their execution will
+overlap as needed.
+The above could be used like this:
+   my $rpc = AnyEvent::Fork
+      ->new
+      ->require ("MyWorker")
+      ->AnyEvent::Fork::RPC::run ("My::Arith::run",
+         on_error => ..., on_event => ..., on_destroy => ...,
+      );
+   $rpc->(add => 1, 3, Coro::rouse_cb); say Coro::rouse_wait;
+   $rpc->(mul => 3, 2, Coro::rouse_cb); say Coro::rouse_wait;
+The C<say>'s will print C<4> and C<6>.
 =head1 PARENT PROCESS USAGE
 This module exports nothing, and only implements a single function:
 =over 4
 Called on (fatal) errors, with a descriptive (hopefully) message. If
 this callback is not provided, but C<on_event> is, then the C<on_event>
 callback is called with the first argument being the string C<error>,
 followed by the error message.
-If neither handler is provided it prints the error to STDERR and will
+If neither handler is provided, then the error is reported with loglevel
-start failing badly.
+C<error> via C<AE::log>.
 =item on_event => $cb->(...)
 Called for every call to the C<AnyEvent::Fork::RPC::event> function in the
 child, with the arguments of that function passed to the callback.
 =over 4
 =item octet strings - C<$AnyEvent::Fork::RPC::STRING_SERIALISER>
 This serialiser concatenates length-prefixes octet strings, and is the
-default.
+default. That means you can only pass (and return) strings containing
+character codes 0-255.
 Implementation:
    (
       sub { pack   "(w/a*)*", @_ },
 =item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER>
 This serialiser uses L<Storable>, which means it has high chance of
 serialising just about anything you throw at it, at the cost of having
-very high overhead per operation. It also comes with perl.
+very high overhead per operation. It also comes with perl. It should be
+used when you need to serialise complex data structures.
 Implementation:
    use Storable ();
    (
    )
 =item portable storable - C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER>
 This serialiser also uses L<Storable>, but uses it's "network" format
-to serialise data, which makes it possible to talk to incompatible
+to serialise data, which makes it possible to talk to different
-perl versions (for example, when talking to a process created with
+perl binaries (for example, when talking to a process created with
 L<AnyEvent::Fork::Remote>).
 Implementation:
    use Storable ();
    my $on_destroy = delete $arg{on_destroy};
    # default for on_error is to on_event, if specified
    $on_error ||= $on_event
                ? sub { $on_event->(error => shift) }
-               : sub { die "AnyEvent::Fork::RPC: uncaught error: $_[0].\n" };
+               : sub { AE::log die => "AnyEvent::Fork::RPC: uncaught error: $_[0]." };
    # default for on_event is to raise an error
    $on_event ||= sub { $on_error->("event received, but no on_event handler") };
    my ($f, $t) = eval $serialiser; die $@ if $@;

Diff Legend

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

Comparing AnyEvent-Fork-RPC/RPC.pm (file contents): Revision 1.28 by root, Sun Apr 28 15:48:31 2013 UTC vs. Revision 1.29 by root, Sun Aug 25 21:52:15 2013 UTC

Diff Legend

Comparing AnyEvent-Fork-RPC/RPC.pm (file contents):
Revision 1.28 by root, Sun Apr 28 15:48:31 2013 UTC vs.
Revision 1.29 by root, Sun Aug 25 21:52:15 2013 UTC