[ViewVC] Diff of: cvs/AnyEvent-Fork/README

Comparing AnyEvent-Fork/README (file contents):
Revision 1.9 by root, Wed Sep 25 11:05:30 2013 UTC vs.
Revision 1.12 by root, Wed Jan 26 16:44:16 2022 UTC

     AnyEvent::Subprocess. There are modules that implement their own process
     management, such as AnyEvent::DBI.
     The problems that all these modules try to solve are real, however, none
     of them (from what I have seen) tackle the very real problems of
-    unwanted memory sharing, efficiency, not being able to use event
+    unwanted memory sharing, efficiency or not being able to use event
-    processing or similar modules in the processes they create.
+    processing, GUI toolkits or similar modules in the processes they
+    create.
     This module doesn't try to replace any of them - instead it tries to
     solve the problem of creating processes with a minimum of fuss and
     overhead (and also luxury). Ideally, most of these would use
     AnyEvent::Fork internally, except they were written before AnyEvent:Fork
         vfork where possible. This gives the speed of vfork, with the
         flexibility of fork.
     Forking usually creates a copy-on-write copy of the parent process.
         For example, modules or data files that are loaded will not use
-        additional memory after a fork. When exec'ing a new process, modules
+        additional memory after a fork. Exec'ing a new process, in contrast,
-        and data files might need to be loaded again, at extra CPU and
+        means modules and data files might need to be loaded again, at extra
-        memory cost. But when forking, literally all data structures are
+        CPU and memory cost.
+        But when forking, you still create a copy of your data structures -
-        copied - if the program frees them and replaces them by new data,
+        if the program frees them and replaces them by new data, the child
-        the child processes will retain the old version even if it isn't
+        processes will retain the old version even if it isn't used, which
-        used, which can suddenly and unexpectedly increase memory usage when
+        can suddenly and unexpectedly increase memory usage when freeing
-        freeing memory.
+        memory.
+        For example, Gtk2::CV is an image viewer optimised for large
+        directories (millions of pictures). It also forks subprocesses for
+        thumbnail generation, which inherit the data structure that stores
+        all file information. If the user changes the directory, it gets
+        freed in the main process, leaving a copy in the thumbnailer
+        processes. This can lead to many times the memory usage that would
+        actually be required. The solution is to fork early (and being
+        unable to dynamically generate more subprocesses or do this from a
+        module)... or to use <AnyEvent:Fork>.
-        The trade-off is between more sharing with fork (which can be good
+        There is a trade-off between more sharing with fork (which can be
-        or bad), and no sharing with exec.
+        good or bad), and no sharing with exec.
         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
         In other words, this module puts you into control over what is being
         shared and what isn't, at all times.
     Exec'ing a new perl process might be difficult.
         For example, it is not easy to find the correct path to the perl
-        interpreter - $^X might not be a perl interpreter at all.
+        interpreter - $^X might not be a perl interpreter at all. Worse,
+        there might not even be a perl binary installed on the system.
         This module 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, but even without help from
         the main program, it will still work when used from a module.
         and modules are no longer loadable because they refer to a different
         perl version, or parts of a distribution are newer than the ones
         already loaded.
         This module supports creating pre-initialised perl processes to be
-        used as a template for new processes.
+        used as a template for new processes at a later time, e.g. for use
+        in a process pool.
     Forking might be impossible when a program is running.
         For example, POSIX makes it almost impossible to fork from a
         multi-threaded program while doing anything useful in the child - in
         fact, 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 without risking corruption issues on a number of operating
+        anymore without risking memory corruption or worse on a number of
-        systems.
+        operating systems.
         This module can safely fork helper processes at any time, by calling
         fork+exec in C, in a POSIX-compatible way (via Proc::FastSpawn).
     Parallel processing with fork might be inconvenient or difficult to
         is still safe to do so) - all other processes are created via
         fork+exec, which makes it possible to use modules such as event
         loops or window interfaces safely.
 EXAMPLES
+    This is where the wall of text ends and code speaks.
   Create a single new process, tell it to run your worker function.
        AnyEvent::Fork
           ->new
           ->require ("MyModule")
           ->run ("MyModule::worker, sub {
        sub worker {
           my ($slave_filehandle) = @_;
           # now $slave_filehandle is connected to the $master_filehandle
-          # in the original prorcess. have fun!
+          # in the original process. have fun!
        }
   Create a pool of server processes all accepting on the same socket.
        # create listener socket
        my $listener = ...;
           ->run ("run", my $cv = AE::cv);
        my $stderr = $cv->recv;
   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
+    When you want to be stingy with files, you can put your code into the
     "DATA" section of your module (or program):
        use AnyEvent::Fork;
        AnyEvent::Fork
        }
   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
+    - even when using a "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
           my ($fh, @args) = @_;
           ...
        }
        # now preserve everything so far as AnyEvent::Fork object
-       # in §TEMPLATE.
+       # 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
         The path to the perl interpreter is divined using various methods -
         first $^X is investigated to see if the path ends with something
         that looks as if it were the perl interpreter. Failing this, the
         module falls back to using $Config::Config{perlpath}.
-        The path to perl can also be overriden by setting the global
+        The path to perl can also be overridden by setting the global
         variable $AnyEvent::Fork::PERL - it's value will be used for all
         subsequent invocations.
     $pid = $proc->pid
         Returns the process id of the process *iff it is a direct child of
         calling this method, and possibly creating a child watcher or reap
         it manually.
     $proc = $proc->eval ($perlcode, @args)
         Evaluates the given $perlcode as ... Perl code, while setting @_ to
-        the strings specified by @args, in the "main" package.
+        the strings specified by @args, in the "main" package (so you can
+        access the args using $_[0] and so on, but not using implicit "shit"
+        as the latter works on @ARGV).
         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.
         See the "use AnyEvent::Fork as a faster fork+exec" example to see it
         in action.
         Returns the process object for easy chaining of method calls.
+        It's common to want to call an iniitalisation function with some
+        arguments. Make sure you actually pass @_ to that function (for
+        example by using &name syntax), and do not just specify a function
+        name:
+           $proc->eval ('&MyModule::init', $string1, $string2);
     $proc = $proc->require ($module, ...)
         Tries to load the given module(s) into the process
         Returns the process object for easy chaining of method calls.
            sub Some::function {
               my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
               print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
            }
+  CHILD PROCESS INTERFACE
+    This module has a limited API for use in child processes.
+    @args = AnyEvent::Fork::Serve::run_args
+        This function, which only exists before the "run" method is called,
+        returns the arguments that would be passed to the run function, and
+        clears them.
+        This is mainly useful to get any file handles passed via "send_fh",
+        but works for any arguments passed via "send_*xxx*" methods.
   EXPERIMENTAL METHODS
     These methods might go away completely or change behaviour, at any time.
     $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
     Cygwin perl is not supported at the moment due to some hilarious
     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.
+USING AnyEvent::Fork IN SUBPROCESSES
+    AnyEvent::Fork itself cannot generally be used in subprocesses. As long
+    as only one process ever forks new processes, sharing the template
+    processes is possible (you could use a pipe as a lock by writing a byte
+    into it to unlock, and reading the byte to lock for example)
+    To make concurrent calls possible after fork, you should get rid of the
+    template and early fork processes. AnyEvent::Fork will create a new
+    template process as needed.
+       undef $AnyEvent::Fork::EARLY;
+       undef $AnyEvent::Fork::TEMPLATE;
+    It doesn't matter whether you get rid of them in the parent or child
+    after a fork.
 SEE ALSO
     AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
     (part of this distribution).
     AnyEvent::Fork::Template, to create a process by forking the main

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-Fork/README (file contents): Revision 1.9 by root, Wed Sep 25 11:05:30 2013 UTC vs. Revision 1.12 by root, Wed Jan 26 16:44:16 2022 UTC

Diff Legend

Comparing AnyEvent-Fork/README (file contents):
Revision 1.9 by root, Wed Sep 25 11:05:30 2013 UTC vs.
Revision 1.12 by root, Wed Jan 26 16:44:16 2022 UTC