=head1 NAME

AnyEvent::ProcessPool - manage pools of perl worker processes, exec'ed or fork'ed

=head1 SYNOPSIS

   use AnyEvent::ProcessPool;

=head1 DESCRIPTION

This module allows you to create single worker processes but also worker
pool that share memory, by forking from the main program, or exec'ing new
perl interpreters from a module.

You create a new processes in a pool by specifying a function to call
with any combination of string values and file handles.

A pool can have initialisation code which is executed before forking. The
initialisation code is only executed once and the resulting process is
cached, to be used as a template.

Pools without such initialisation code don't cache an extra process.

=head1 PROBLEM STATEMENT

There are two ways to implement parallel processing on UNIX like operating
systems - fork and process, and fork+exec and process. They have different
advantages and disadvantages that I describe below, together with how this
module tries to mitigate the disadvantages.

=over 4

=item Forking from a big process can be very slow (a 5GB process needs
0.05s to fork on my 3.6GHz amd64 GNU/Linux box for example). This overhead
is often shared with exec (because you have to fork first), but in some
circumstances (e.g. when vfork is used), fork+exec can be much faster.

This module can help here by telling a small(er) helper process to fork,
or fork+exec instead.

=item Forking usually creates a copy-on-write copy of the parent
process. Memory (for example, modules or data files that have been
will not take additional memory). When exec'ing a new process, modules
and data files might need to be loaded again, at extra cpu and memory
cost. Likewise when forking, all data structures are copied as well - if
the program frees them and replaces them by new data, the child processes
will retain the memory even if it isn't used.

This module allows the main program to do a controlled fork, and allows
modules to exec processes safely at any time. When creating a custom
process pool you can take advantage of data sharing via fork without
risking to share large dynamic data structures that will blow up child
memory usage.

=item Exec'ing a new perl process might be difficult and slow. For
example, it is not easy to find the correct path to the perl interpreter,
and all modules have to be loaded from disk again. Long running processes
might run into problems when perl is upgraded for example.

This module supports creating pre-initialised perl processes to be used
as template, and also tries hard to identify the correct path to the perl
interpreter. With a cooperative main program, exec'ing the interpreter
might not even be necessary.

=item Forking might be impossible when a program is running. For example,
POSIX makes it almost impossible to fork from a multithreaded program and
do anything useful in the child - strictly speaking, if your perl program
uses posix threads (even indirectly via e.g. L<IO::AIO> or L<threads>),
you cannot call fork on the perl level anymore, at all.

This module can safely fork helper processes at any time, by caling
fork+exec in C, in a POSIX-compatible way.

=item Parallel processing with fork might be inconvenient or difficult
to implement. For example, when a program uses an event loop and creates
watchers it becomes very hard to use the event loop from a child
program, as the watchers already exist but are only meaningful in the
parent. Worse, a module might want to use such a system, not knowing
whether another module or the main program also does, leading to problems.

This module only lets the main program create pools by forking (because
only the main program can know when it is still safe to do so) - all other
pools are created by fork+exec, after which such modules can again be
loaded.

=back

=over 4

=cut

package AnyEvent::ProcessPool;

use common::sense;

use Socket ();

use Proc::FastSpawn;
use AnyEvent;
use AnyEvent::ProcessPool::Util;
use AnyEvent::Util ();

BEGIN {
#   require Exporter;
}

=item my $pool = new AnyEvent::ProcessPool key => value...

Create a new process pool. The following named parameters are supported:

=over 4

=back

=cut

# the template process
our $template;

sub _queue {
   my ($pid, $fh) = @_;

   [
      $pid,
      $fh,
      [],
      undef
   ]
}

sub queue_cmd {
   my ($queue, $cmd) = @_;

   push @{ $queue->[2] }, pack "N/a", $cmd;

   $queue->[3] ||= AE::io $queue->[1], 1, sub {
      warn "oopl0 ", scalar @{ $queue->[2] };
      if (ref $queue->[2][0]) {
         warn "oopla2\n";#d#
         AnyEvent::ProcessPool::Util::fd_send fileno $queue->[1], fileno ${ $queue->[2][0] }
            and shift @{ $queue->[2] };
      } else {
         warn "write ", length $queue->[2][0];#d#
         my $len = syswrite $queue->[1], $queue->[2][0]
            or die "AnyEvent::ProcessPool::queue write failure: $!";
         substr $queue->[2][0], 0, $len, "";
         shift @{ $queue->[2] } unless length $queue->[2][0];
      }

      undef $queue->[3] unless @{ $queue->[2] };
      warn "oopl3 ", scalar @{ $queue->[2] };
      warn "oopl4 $queue->[3]\n";#d#
   };
}

sub run_template {
   return if $template;

   my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
   AnyEvent::Util::fh_nonblocking $fh, 1;
   fd_inherit fileno $slave;

   my %env = %ENV;
   $env{PERL5LIB} = join ":", grep !ref, @INC;

   my $pid = spawn
         $^X,
         ["perl", "-MAnyEvent::ProcessPool::Serve", "-e", "AnyEvent::ProcessPool::Serve::me", fileno $slave],
         [map "$_=$env{$_}", keys %env],
      or die "unable to spawn AnyEvent::ProcessPool server: $!";

   close $slave;

   $template = _queue $pid, $fh;

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

   queue_cmd $template, "Iabc";
   push @{ $template->[2] }, \$b;

   use Coro::AnyEvent; Coro::AnyEvent::sleep 1;
}

sub new {
   my $class = shift;

   my $self = bless {
      @_
   }, $class;

   run_template;

   $self
}

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1