--- AnyEvent-Fork/README	2013/04/18 20:17:35	1.6
+++ AnyEvent-Fork/README	2013/04/21 12:26:00	1.7
@@ -36,7 +36,11 @@
     companion module, which adds simple RPC/job queueing to a process
     created by this module.
 
-    Or you can implement it yourself in whatever way you like, use some
+    And if you need some automatic process pool management on top of
+    AnyEvent::Fork::RPC, you can look at the AnyEvent::Fork::Pool companion
+    module.
+
+    Or you can implement it yourself in whatever way you like: use some
     message-passing module such as AnyEvent::MP, some pipe such as
     AnyEvent::ZeroMQ, use AnyEvent::Handle on both sides to send e.g. JSON
     or Storable messages, and so on.
@@ -235,7 +239,75 @@
 
        my $stderr = $cv->recv;
 
-CONCEPTS
+  For stingy users: put the worker code into a "DATA" section.
+    When you want to be stingy with files, you cna put your code into the
+    "DATA" section of your module (or program):
+
+       use AnyEvent::Fork;
+
+       AnyEvent::Fork
+          ->new
+          ->eval (do { local $/; <DATA> })
+          ->run ("doit", sub { ... });
+
+       __DATA__
+
+       sub doit {
+          ... do something!
+       }
+
+  For stingy standalone programs: do not rely on external files at
+all.
+    For single-file scripts it can be inconvenient to rely on external files
+    - even when using < "DATA" section, you still need to "exec" an external
+    perl interpreter, which might not be available when using
+    App::Staticperl, Urlader or PAR::Packer for example.
+
+    Two modules help here - AnyEvent::Fork::Early forks a template process
+    for all further calls to "new_exec", and AnyEvent::Fork::Template forks
+    the main program as a template process.
+
+    Here is how your main program should look like:
+
+       #! perl
+
+       # optional, as the very first thing.
+       # in case modules want to create their own processes.
+       use AnyEvent::Fork::Early;
+
+       # next, load all modules you need in your template process
+       use Example::My::Module
+       use Example::Whatever;
+
+       # next, put your run function definition and anything else you
+       # need, but do not use code outside of BEGIN blocks.
+       sub worker_run {
+          my ($fh, @args) = @_;
+          ...
+       }
+
+       # now preserve everything so far as AnyEvent::Fork object
+       # in §TEMPLATE.
+       use AnyEvent::Fork::Template;
+
+       # do not put code outside of BEGIN blocks until here
+
+       # now use the $TEMPLATE process in any way you like
+
+       # for example: create 10 worker processes
+       my @worker;
+       my $cv = AE::cv;
+       for (1..10) {
+          $cv->begin;
+          $TEMPLATE->fork->send_arg ($_)->run ("worker_run", sub {
+             push @worker, shift;
+             $cv->end;
+          });
+       }
+       $cv->recv;
+
+    lhead1 CONCEPTS
+
     This module can create new processes either by executing a new perl
     process, or by forking from an existing "template" process.
 
@@ -506,6 +578,29 @@
               print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
            }
 
+    $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
+        Flushes all commands out to the process and then calls the callback
+        with the communications socket.
+
+        The process object becomes unusable on return from this function -
+        any further method calls result in undefined behaviour.
+
+        The point of this method is to give you a file handle thta you cna
+        pass to another process. In that other process, you can call
+        "new_from_fh AnyEvent::Fork" to create a new "AnyEvent::Fork" object
+        from it, thereby effectively passing a fork object to another
+        process.
+
+    new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
+        Takes a file handle originally rceeived by the "to_fh" method and
+        creates a new "AnyEvent:Fork" object. The child process itself will
+        not change in any way, i.e. it will keep all the modifications done
+        to it before calling "to_fh".
+
+        The new object is very much like the original object, except that
+        the "pid" method will return "undef" even if the process is a direct
+        child.
+
 PERFORMANCE
     Now for some unscientific benchmark numbers (all done on an amd64
     GNU/Linux box). These are intended to give you an idea of the relative
@@ -521,7 +616,7 @@
 
     Then I did the same thing, but instead of calling fork, I called
     AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the
-    socket form the child to close on exit. This does the same thing as
+    socket from the child to close on exit. This does the same thing as
     manual socket pair + fork, except that what is forked is the template
     process (2440kB), and the socket needs to be passed to the server at the
     other end of the socket first.
@@ -631,8 +726,15 @@
     yet to see something useful that you can do with it without running into
     memory corruption issues or other braindamage. Hrrrr.
 
+    Since fork is endlessly broken on win32 perls (it doesn't even remotely
+    work within it's documented limits) and quite obviously it's not getting
+    improved any time soon, the best way to proceed on windows would be to
+    always use "new_exec" and thus never rely on perl's fork "emulation".
+
     Cygwin perl is not supported at the moment due to some hilarious
-    shortcomings of its API - see IO::FDPoll for more details.
+    shortcomings of its API - see IO::FDPoll for more details. If you never
+    use "send_fh" and always use "new_exec" to create processes, it should
+    work though.
 
 SEE ALSO
     AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
@@ -643,6 +745,8 @@
 
     AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
 
+    AnyEvent::Fork::Pool, for simple worker process pool (on CPAN).
+
 AUTHOR AND CONTACT INFORMATION
      Marc Lehmann <schmorp@schmorp.de>
      http://software.schmorp.de/pkg/AnyEvent-Fork