view release on metacpan or  search on metacpan

README  view on Meta::CPAN

       for (1..10) {
          $pool->(doit => $_, sub {
             print "MyWorker::run returned @_\n";
          });
       }

       undef $pool;

       $finish->recv;

DESCRIPTION
    This module uses processes created via AnyEvent::Fork (or
    AnyEvent::Fork::Remote) and the RPC protocol implement in
    AnyEvent::Fork::RPC to create a load-balanced pool of processes that
    handles jobs.

    Understanding AnyEvent::Fork is helpful but not required to use this
    module, but a thorough understanding of AnyEvent::Fork::RPC is, as it
    defines the actual API that needs to be implemented in the worker
    processes.

PARENT USAGE
    To create a pool, you first have to create a AnyEvent::Fork object -
    this object becomes your template process. Whenever a new worker process
    is needed, it is forked from this template process. Then you need to
    "hand off" this template process to the "AnyEvent::Fork::Pool" module by
    calling its run method on it:

       my $template = AnyEvent::Fork
                         ->new
                         ->require ("SomeModule", "MyWorkerModule");

       my $pool = $template->AnyEvent::Fork::Pool::run ("MyWorkerModule::myfunction");

    The pool "object" is not a regular Perl object, but a code reference
    that you can call and that works roughly like calling the worker
    function directly, except that it returns nothing but instead you need
    to specify a callback to be invoked once results are in:

       $pool->(1, 2, 3, sub { warn "myfunction(1,2,3) returned @_" });

    my $pool = AnyEvent::Fork::Pool::run $fork, $function, [key => value...]
        The traditional way to call the pool creation function. But it is
        way cooler to call it in the following way:

    my $pool = $fork->AnyEvent::Fork::Pool::run ($function, [key =>
    value...])
        Creates a new pool object with the specified $function as function
        (name) to call for each request. The pool uses the $fork object as
        the template when creating worker processes.

        You can supply your own template process, or tell
        "AnyEvent::Fork::Pool" to create one.

        A relatively large number of key/value pairs can be specified to
        influence the behaviour. They are grouped into the categories "pool
        management", "template process" and "rpc parameters".

        Pool Management
            The pool consists of a certain number of worker processes. These
            options decide how many of these processes exist and when they
            are started and stopped.

            The worker pool is dynamically resized, according to (perceived
            :) load. The minimum size is given by the "idle" parameter and
            the maximum size is given by the "max" parameter. A new worker
            is started every "start" seconds at most, and an idle worker is
            stopped at most every "stop" second.

            You can specify the amount of jobs sent to a worker concurrently
            using the "load" parameter.

            idle => $count (default: 0)
                The minimum amount of idle processes in the pool - when
                there are fewer than this many idle workers,
                "AnyEvent::Fork::Pool" will try to start new ones, subject
                to the limits set by "max" and "start".

                This is also the initial amount of workers in the pool. The
                default of zero means that the pool starts empty and can
                shrink back to zero workers over time.

            max => $count (default: 4)
                The maximum number of processes in the pool, in addition to
                the template process. "AnyEvent::Fork::Pool" will never have
                more than this number of worker processes, although there
                can be more temporarily when a worker is shut down and
                hasn't exited yet.

            load => $count (default: 2)
                The maximum number of concurrent jobs sent to a single
                worker process.

                Jobs that cannot be sent to a worker immediately (because
                all workers are busy) will be queued until a worker is
                available.

                Setting this low improves latency. For example, at 1, every
                job that is sent to a worker is sent to a completely idle
                worker that doesn't run any other jobs. The downside is that
                throughput is reduced - a worker that finishes a job needs
                to wait for a new job from the parent.

                The default of 2 is usually a good compromise.

            start => $seconds (default: 0.1)
                When there are fewer than "idle" workers (or all workers are
                completely busy), then a timer is started. If the timer
                elapses and there are still jobs that cannot be queued to a
                worker, a new worker is started.

                This sets the minimum time that all workers must be busy
                before a new worker is started. Or, put differently, the
                minimum delay between starting new workers.

                The delay is small by default, which means new workers will
                be started relatively quickly. A delay of 0 is possible, and
                ensures that the pool will grow as quickly as possible under
                load.

                Non-zero values are useful to avoid "exploding" a pool