view release on metacpan or  search on metacpan

Fork.pm  view on Meta::CPAN

Returns the process object for easy chaining of method calls.

Example: pass a file handle to a process, and release it without
closing. It will be closed automatically when it is no longer used.

   $proc->send_fh ($my_fh);
   undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT

=cut

sub send_fh {
   my ($self, @fh) = @_;

   for my $fh (@fh) {
      $self->_cmd ("h");
      push @{ $self->[QUEUE] }, \$fh;
   }

   $self
}

=item $proc = $proc->send_arg ($string, ...)

Send one or more argument strings to the process, to prepare a call to
C<run>. The strings can be any octet strings.

The protocol is optimised to pass a moderate number of relatively short
strings - while you can pass up to 4GB of data in one go, this is more
meant to pass some ID information or other startup info, not big chunks of
data.

Returns the process object for easy chaining of method calls.

=cut

sub send_arg {
   my ($self, @arg) = @_;

   $self->_cmd (a => pack "(w/a*)*", @arg);

   $self
}

=item $proc->run ($func, $cb->($fh))

Enter the function specified by the function name in C<$func> in the
process. The function is called with the communication socket as first
argument, followed by all file handles and string arguments sent earlier
via C<send_fh> and C<send_arg> methods, in the order they were called.

The process object becomes unusable on return from this function - any
further method calls result in undefined behaviour.

The function name should be fully qualified, but if it isn't, it will be
looked up in the C<main> package.

If the called function returns, doesn't exist, or any error occurs, the
process exits.

Preparing the process is done in the background - when all commands have
been sent, the callback is invoked with the local communications socket
as argument. At this point you can start using the socket in any way you
like.

If the communication socket isn't used, it should be closed on both sides,
to save on kernel memory.

The socket is non-blocking in the parent, and blocking in the newly
created process. The close-on-exec flag is set in both.

Even if not used otherwise, the socket can be a good indicator for the
existence of the process - if the other process exits, you get a readable
event on it, because exiting the process closes the socket (if it didn't
create any children using fork).

=over 4

=item Compatibility to L<AnyEvent::Fork::Remote>

If you want to write code that works with both this module and
L<AnyEvent::Fork::Remote>, you need to write your code so that it assumes
there are two file handles for communications, which might not be unix
domain sockets. The C<run> function should start like this:

   sub run {
      my ($rfh, @args) = @_; # @args is your normal arguments
      my $wfh = fileno $rfh ? $rfh : *STDOUT;

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

This checks whether the passed file handle is, in fact, the process
C<STDIN> handle. If it is, then the function was invoked visa
L<AnyEvent::Fork::Remote>, so STDIN should be used for reading and
C<STDOUT> should be used for writing.

In all other cases, the function was called via this module, and there is
only one file handle that should be sued for reading and writing.

=back

Example: create a template for a process pool, pass a few strings, some
file handles, then fork, pass one more string, and run some code.

   my $pool = AnyEvent::Fork
                 ->new
                 ->send_arg ("str1", "str2")
                 ->send_fh ($fh1, $fh2);

   for (1..2) {
      $pool
         ->fork
         ->send_arg ("str3")
         ->run ("Some::function", sub {
            my ($fh) = @_;

            # fh is nonblocking, but we trust that the OS can accept these
            # few octets anyway.
            syswrite $fh, "hi #$_\n";