NAME
   AnyEvent::Fork::Remote - remote processes with AnyEvent::Fork interface

   THE API IS NOT FINISHED, CONSIDER THIS A BETA RELEASE

SYNOPSIS
      use AnyEvent;
      use AnyEvent::Fork::Remote;

      my $rpc = AnyEvent::Fork::Remote
         ->new_execp ("ssh", "ssh", "othermachine", "perl")
         ->require ("MyModule")
         ->run ("MyModule::run", my $cv = AE::cv);

      my $fh = $cv->recv;

DESCRIPTION
   Despite what the name of this module might suggest, it doesn't actually
   create remote processes for you. But it does make it easy to use them,
   once you have started them.

   This module implements a very similar API as AnyEvent::Fork. In fact,
   similar enough to require at most minor modifications to support both at
   the same time. For example, it works with AnyEvent::Fork::RPC and
   AnyEvent::Fork::Pool.

   The documentation for this module will therefore only document the parts
   of the API that differ between the two modules.

 SUMMARY OF DIFFERENCES
   Here is a short summary of the main differences between AnyEvent::Fork
   and this module:

   *   "send_fh" is not implemented and will fail

   *   the child-side "run" function must read from STDIN and write to
       STDOUT

   *   "fork" does not actually fork, but will create a new process

EXAMPLE
   This example uses a local perl (because that is likely going to work
   without further setup) and the AnyEvent::Fork::RPC to create simple
   worker process.

   First load the modules we are going to use:

      use AnyEvent;
      use AnyEvent::Fork::Remote;
      use AnyEvent::Fork::RPC;

   Then create, configure and run the process:

      my $rpc = AnyEvent::Fork::Remote
         ->new_execp ("perl", "perl")
         ->eval ('
              sub myrun {
                 "this is process $$, and you passed <@_>"
              }
           ')
         ->AnyEvent::Fork::RPC::run ("myrun");

   We use "new_execp" to execute the first perl found in the PATH. You'll
   have to make sure there is one for this to work. The perl does not
   actually have to be the same perl as the one running the example, and it
   doesn't need to have any modules installed.

   The reason we have to specify "perl" twice is that the first argument to
   "new_execp" (and also "new_exec") is the program name or path, while the
   remaining ones are the arguments, and the first argument passed to a
   program is the program name, so it has to be specified twice.

   Finally, the standard example, send some numbers to the remote function,
   and print whatever it returns:

      my $cv = AE::cv;

      for (1..10) {
         $cv->begin;
         $rpc->($_, sub {
            print "remote function returned: $_[0]\n";
            $cv->end;
         });
      }

      $cv->recv;

   Now, executing perl in the PATH isn't very interesting - you could have
   done the same with AnyEvent::Fork, and it might even be more efficient.

   The power of this module is that the perl doesn't need to run on the
   local box, you could simply substitute another command, such as ssh
   remotebox perl:

      my $rpc = AnyEvent::Fork::Remote
         ->new_execp ("ssh", "ssh", "remotebox", "perl")

   And if you want to use a specific path for ssh, use "new_exec":

      my $rpc = AnyEvent::Fork::Remote
         ->new_exec ("/usr/bin/ssh", "ssh", "remotebox", "perl")

   Of course, it doesn't really matter to this module how you construct
   your perl processes, what matters is that somehow, you give it a file
   handle connected to the new perls STDIN and STDOUT.

PARENT PROCESS USAGE
   my $proc = new_exec AnyEvent::Fork::Remote $path, @args...
       Creates a new "AnyEvent::Fork::Remote" object. Unlike
       AnyEvent::Fork, processes are only created when "run" is called,
       every other method call is is simply recorded until then.

       Each time a new process is needed, it executes $path with the given
       arguments (the first array member must be the program name, as with
       the "exec" function with explicit PROGRAM argument) and both "STDIN"
       and "STDOUT" connected to a communications socket. No input must be
       consumed by the command before perl is started, and no output should
       be generated.

       The program *must* invoke perl somehow, with STDIN and STDOUT
       intact, without specifying anything to execute (no script file name,
       no "-e" switch etc.).

       Here are some examples to give you an idea:

          # just "perl"
          $proc = new_exec AnyEvent::Fork::Remote
             "/usr/bin/perl", "perl";

          # rsh othernode exec perl
          $proc = new_exec AnyEvent::Fork::Remote
             "/usr/bin/rsh", "rsh", "othernode", "exec perl";

          # a complicated ssh command
          $proc = new_exec AnyEvent::Fork::Remote
             "/usr/bin/ssh",
             qw(ssh -q
                -oCheckHostIP=no -oTCPKeepAlive=yes -oStrictHostKeyChecking=no
                -oGlobalKnownHostsFile=/dev/null -oUserKnownHostsFile=/dev/null
                otherhost
                exec perl);

   my $proc = new_execp AnyEvent::Fork::Remote $file, @args...
       Just like "new_exec", except that the program is searched in the
       $ENV{PATH} first, similarly to how the shell does it. This makes it
       easier to find e.g. "ssh":

          $proc = new_execp AnyEvent::Fork::Remote "ssh", "ssh", "otherhost", "perl";

   my $proc = new AnyEvent::Fork::Remote $create_callback
       Basically the same as "new_exec", but instead of a command to
       execute, it expects a callback which is invoked each time a process
       needs to be created.

       The $create_callback is called with another callback as argument,
       and should call this callback with the file handle that is connected
       to a perl process. This callback can be invoked even after the
       $create_callback returns.

       Example: emulate "new_exec" using "new".

          use AnyEvent::Util;
          use Proc::FastSpawn;

          $proc = new AnyEvent::Fork::Remote sub {
             my $done = shift;

             my ($a, $b) = AnyEvent::Util::portable_socketpair
                or die;

             open my $oldin , "<&0" or die;
             open my $oldout, ">&1" or die;

             open STDIN , "<&" . fileno $b or die;
             open STDOUT, ">&" . fileno $b or die;

             spawn "/usr/bin/rsh", ["rsh", "othernode", "perl"];

             open STDIN , "<&" . fileno $oldin ;
             open STDOUT, ">&" . fileno $oldout;

             $done->($a);
          };

   my $proc = new_from_fh $fh
       Creates an "AnyEvent::Fork::Remote" object from a file handle. This
       file handle must be connected to both STDIN and STDOUT of a perl
       process.

       This form might be more convenient than "new" or "new_exec" when
       creating an "AnyEvent::Fork::Remote" object, but the resulting
       object does not support "fork".

   $new_proc = $proc->fork
       Quite the same as the same method of AnyEvent::Fork, except that it
       simply clones the object without creating an actual process.

   undef = $proc->pid
       The "pid" method always returns "undef" and only exists for
       compatibility with AnyEvent::Fork.

   $proc = $proc->send_fh (...)
       Not supported and always croaks.

   $proc = $proc->eval ($perlcode, @args)
       Quite the same as the same method of AnyEvent::Fork.

   $proc = $proc->require ($module, ...)
       Quite the same as the same method of AnyEvent::Fork.

   $proc = $proc->send_arg ($string, ...)
       Quite the same as the same method of AnyEvent::Fork.

   $proc->run ($func, $cb->($fh))
       Very similar to the run method of AnyEvent::Fork.

       On the parent side, the API is identical, except that a $cb argument
       of "undef" instead of a valid file handle signals an error.

       On the child side, the "communications socket" is in fact just
       *STDIN, and typically can only be read from (this highly depends on
       how the program is created - if you just run perl locally, it will
       work for both reading and writing, but commands such as rsh or ssh
       typically only provide read-only handles for STDIN).

       To be portable, if the run function wants to read data that is
       written to $fh in the parent, then it should read from STDIN. If the
       run function wants to provide data that can later be read from $fh,
       then it should write them to STDOUT.

       You can write a run function that works with both AnyEvent::Fork and
       this module by checking "fileno $fh". If it is 0 (meaning it is
       STDIN), then you should use it for reading, and STDOUT for writing.
       Otherwise, you should use the file handle for both:

          sub run {
             my ($rfh, ...) = @_;
             my $wfh = fileno $rfh ? $rfh : *STDOUT;

             # now use $rfh for reading and $wfh for writing
          }

SEE ALSO
   AnyEvent::Fork, the same as this module, for local processes.

   AnyEvent::Fork::RPC, to talk to the created processes.

   AnyEvent::Fork::Pool, to manage whole pools of processes.

AUTHOR AND CONTACT INFORMATION
    Marc Lehmann <[email protected]>
    http://software.schmorp.de/pkg/AnyEvent-Fork-Remote

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.