view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        the handles. This is most easily accomplished by simply not storing
        the file handles anywhere after passing them to this method - when
        AnyEvent::Fork is finished using them, perl will automatically close
        them.

        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

    $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 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.

    $proc->run ($func, $cb->($fh))
        Enter the function specified by the function 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.

        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 "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).

        Compatibility to AnyEvent::Fork::Remote
            If you want to write code that works with both this module and
            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 "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 "STDIN" handle. If it is, then the function was invoked
            visa AnyEvent::Fork::Remote, so STDIN should be used for reading
            and "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.

        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";

                    # $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" 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.