NAME
AnyEvent::Fork - everything you wanted to use fork() for, but couldn't
SYNOPSIS
use AnyEvent::Fork;
##################################################################
# create a single new process, tell it to run your worker function
AnyEvent::Fork
->new
->require ("MyModule")
->run ("MyModule::worker, sub {
my ($master_filehandle) = @_;
# now $master_filehandle is connected to the
# $slave_filehandle in the new process.
});
# MyModule::worker might look like this
sub MyModule::worker {
my ($slave_filehandle) = @_;
# now $slave_filehandle is connected to the $master_filehandle
# in the original prorcess. have fun!
}
##################################################################
# create a pool of server processes all accepting on the same socket
# create listener socket
my $listener = ...;
# create a pool template, initialise it and give it the socket
my $pool = AnyEvent::Fork
->new
->require ("Some::Stuff", "My::Server")
->send_fh ($listener);
# now create 10 identical workers
for my $id (1..10) {
$pool
->fork
->send_arg ($id)
->run ("My::Server::run");
}
# now do other things - maybe use the filehandle provided by run
# to wait for the processes to die. or whatever.
# My::Server::run might look like this
sub My::Server::run {
my ($slave, $listener, $id) = @_;
close $slave; # we do not use the socket, so close it to save resources
# we could go ballistic and use e.g. AnyEvent here, or IO::AIO,
# or anything we usually couldn't do in a process forked normally.
while (my $socket = $listener->accept) {
# do sth. with new socket
}
}
DESCRIPTION
This module allows you to create new processes, without actually forking
them from your current process (avoiding the problems of forking), but
preserving most of the advantages of fork.
It can be used to create new worker processes or new independent
subprocesses for short- and long-running jobs, process pools (e.g. for
use in pre-forked servers) but also to spawn new external processes
(such as CGI scripts from a webserver), which can be faster (and more
well behaved) than using fork+exec in big processes.
Special care has been taken to make this module useful from other
modules, while still supporting specialised environments such as
App::Staticperl or PAR::Packer.
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.
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.
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.
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.
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. IO::AIO or
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.
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.
CONCEPTS
This module can create new processes either by executing a new perl
process, or by forking from an existing "template" process.
Each such process comes with its own file handle that can be used to
communicate with it (it's actually a socket - one end in the new
process, one end in the main process), and among the things you can do
in it are load modules, fork new processes, send file handles to it, and
execute functions.
There are multiple ways to create additional processes to execute some
jobs:
fork a new process from the "default" template process, load code, run
it
This module has a "default" template process which it executes when
it is needed the first time. Forking from this process shares the
memory used for the perl interpreter with the new process, but
loading modules takes time, and the memory is not shared with
anything else.
This is ideal for when you only need one extra process of a kind,
with the option of starting and stipping it on demand.
Example:
AnyEvent::Fork
->new
->require ("Some::Module")
->run ("Some::Module::run", sub {
my ($fork_fh) = @_;
});
fork a new template process, load code, then fork processes off of it
and run the code
When you need to have a bunch of processes that all execute the same
(or very similar) tasks, then a good way is to create a new template
process for them, loading all the modules you need, and then create
your worker processes from this new template process.
This way, all code (and data structures) that can be shared (e.g.
the modules you loaded) is shared between the processes, and each
new process consumes relatively little memory of its own.
The disadvantage of this approach is that you need to create a
template process for the sole purpose of forking new processes from
it, but if you only need a fixed number of proceses you can create
them, and then destroy the template process.
Example:
my $template = AnyEvent::Fork->new->require ("Some::Module");
for (1..10) {
$template->fork->run ("Some::Module::run", sub {
my ($fork_fh) = @_;
});
}
# at this point, you can keep $template around to fork new processes
# later, or you can destroy it, which causes it to vanish.
execute a new perl interpreter, load some code, run it
This is relatively slow, and doesn't allow you to share memory
between multiple processes.
The only advantage is that you don't have to have a template process
hanging around all the time to fork off some new processes, which
might be an advantage when there are long time spans where no extra
processes are needed.
Example:
AnyEvent::Fork
->new_exec
->require ("Some::Module")
->run ("Some::Module::run", sub {
my ($fork_fh) = @_;
});
FUNCTIONS
my $pool = new AnyEvent::Fork key => value...
Create a new process pool. The following named parameters are
supported:
my $proc = new AnyEvent::Fork
Create a new "empty" perl interpreter process and returns its
process object for further manipulation.
The new process is forked from a template process that is kept
around for this purpose. When it doesn't exist yet, it is created by
a call to "new_exec" and kept around for future calls.
When the process object is destroyed, it will release the file
handle that connects it with the new process. When the new process
has not yet called "run", then the process will exit. Otherwise,
what happens depends entirely on the code that is executed.
$new_proc = $proc->fork
Forks $proc, creating a new process, and returns the process object
of the new process.
If any of the "send_" functions have been called before fork, then
they will be cloned in the child. For example, in a pre-forked
server, you might "send_fh" the listening socket into the template
process, and then keep calling "fork" and "run".
my $proc = new_exec AnyEvent::Fork
Create a new "empty" perl interpreter process and returns its
process object for further manipulation.
Unlike the "new" method, this method *always* spawns a new perl
process (except in some cases, see AnyEvent::Fork::Early for
details). This reduces the amount of memory sharing that is
possible, and is also slower.
You should use "new" whenever possible, except when having a
template process around is unacceptable.
The path to the perl interpreter is divined usign various methods -
first $^X is investigated to see if the path ends with something
that sounds as if it were the perl interpreter. Failing this, the
module falls back to using $Config::Config{perlpath}.
$proc = $proc->eval ($perlcode, @args)
Evaluates the given $perlcode as ... perl code, while setting @_ to
the strings specified by @args.
This call is meant to do any custom initialisation that might be
required (for example, the "require" method uses it). It's not
supposed to be used to completely take over the process, use "run"
for that.
The code will usually be executed after this call returns, and there
is no way to pass anything back to the calling process. Any
evaluation errors will be reported to stderr and cause the process
to exit.
Returns the process object for easy chaining of method calls.
$proc = $proc->require ($module, ...)
Tries to load the given module(s) into the process
Returns the process object for easy chaining of method calls.
$proc = $proc->send_fh ($handle, ...)
Send one or more file handles (*not* file descriptors) to the
process, to prepare a call to "run".
The process object keeps a reference to the handles until this is
done, so you must not explicitly close the handles. This is most
easily accomplished by simply not storing the file handles anywhere
after passing them to this method.
Returns the process object for easy chaining of method calls.
Example: pass an fh 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
$proc = $proc->send_arg ($string, ...)
Send one or more argument strings to the process, to prepare a call
to "run". The strings can be any octet string.
Returns the process object for easy chaining of emthod calls.
$proc->run ($func, $cb->($fh))
Enter the function specified by the fully qualified name in $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 "send_fh" and "send_arg" methods, in the order they
were called.
If the called function returns, the process exits.
Preparing the process can take time - when the process is ready, the
callback is invoked with the local communications socket as
argument.
The process object becomes unusable on return from this function.
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 on both. Even if not
used otherwise, the socket can be a good indicator for the existance
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).
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
# extra 3 octets anyway.
syswrite $fh, "hi #$_\n";
# $fh is being closed here, as we don't store it anywhere
});
}
# Some::function might look like this - all parameters passed before fork
# and after will be passed, in order, after the communications socket.
sub Some::function {
my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
print scalar <$fh>; # prints "hi 1\n" and "hi 2\n"
}
TYPICAL PROBLEMS
This section lists typical problems that remain. I hope by recognising
them, most can be avoided.
"leaked" file descriptors for exec'ed processes
POSIX systems inherit file descriptors by default when exec'ing a
new process. While perl itself laudably sets the close-on-exec flags
on new file handles, most C libraries don't care, and even if all
cared, it's often not possible to set the flag in a race-free
manner.
That means some file descriptors can leak through. And since it
isn't possible to know which file descriptors are "good" and
"neccessary" (or even to know which file descreiptors are open),
there is no good way to close the ones that might harm.
As an example of what "harm" can be done consider a web server that
accepts connections and afterwards some module uses AnyEvent::Fork
for the first time, causing it to fork and exec a new process, which
might inherit the network socket. When the server closes the socket,
it is still open in the child (which doesn't even know that) and the
client might conclude that the connection is still fine.
For the main program, there are multiple remedies available -
AnyEvent::Fork::Early is one, creating a process early and not using
"new_exec" is another, as in both cases, the first process can be
exec'ed well before many random file descriptors are open.
In general, the solution for these kind of problems is to fix the
libraries or the code that leaks those file descriptors.
Fortunately, most of these lekaed descriptors do no harm, other than
sitting on some resources.
"leaked" file descriptors for fork'ed processes
Normally, AnyEvent::Fork does start new processes by exec'ing them,
which closes file descriptors not marked for being inherited.
However, AnyEvent::Fork::Early and AnyEvent::Fork::Template offer a
way to create these processes by forking, and this leaks more file
descriptors than exec'ing them, as there is no way to mark
descriptors as "close on fork".
An example would be modules like EV, IO::AIO or Gtk2. Both create
pipes for internal uses, and Gtk2 might open a connection to the X
server. EV and IO::AIO can deal with fork, but Gtk2 might have
trouble with a fork.
The solution is to either not load these modules before use'ing
AnyEvent::Fork::Early or AnyEvent::Fork::Template, or to delay
initialising them, for example, by calling "init Gtk2" manually.
PORTABILITY NOTES
Native win32 perls are somewhat supported (AnyEvent::Fork::Early is a
nop, and ::Template is not going to work), and it cost a lot of blood
and sweat to make it so, mostly due to the bloody broken perl that
nobody seems to care about. The fork emulation is a bad joke - I have
yet to see something useful that you cna do with it without running into
memory corruption issues or other braindamage. Hrrrr.
Cygwin perl is not supported at the moment, as it should implement fd
passing, but doesn't, and rolling my own is hard, as cygwin doesn't
support enough functionality to do it.
SEE ALSO
AnyEvent::Fork::Early (to avoid executing a perl interpreter),
AnyEvent::Fork::Template (to create a process by forking the main
program at a convenient time).
AUTHOR
Marc Lehmann
http://home.schmorp.de/
ftp://ftp.auckland.ac.nz/pub/perl/CPAN/authors/Marc_Lehmann/AnyEvent-Fork-0.2.readme
