View on
Eric Waters > POE-Component-PreforkDispatch-0.101 > POE::Component::PreforkDispatch



Annotate this POD


New  2
Open  1
View/Report Bugs
Module Version: 0.101   Source  


POE::Component::PreforkDispatch - Preforking task dispatcher


Applications that require lots of asynchronous tasks going at once may suffer a performance hit from repeating the fork/die process over and over again with each enqueued job. Similar to how Apache forks, this dispatcher will maintain a pool of available forks and a queue of pending tasks. Each task (request) will be handled in turn, and will return to the callback when done.


    use POE qw(Component::PreforkDispatch);

        inline_states => {
            _start => \&start,
            do_slow_task => \&task,
            do_slow_task_cb => \&task_cb,


    sub start {
            max_forks => 4,
            pre_fork  => 2,
        foreach (1..5) {
            print "Enqueued request $_\n";
            $poe_kernel->post(PreforkDispatch => 'new_request', {
                method      => 'do_slow_task',
                upon_result => 'do_slow_task_cb',
                params      => [ 'a value', $_, ],

    sub task {
        my ($kernel, $heap, $from, $param1, $param2) = @_[KERNEL, HEAP, ARG0 .. $#_];

        # ... do something slow
        print STDERR "Task running with '$param1', '$param2'\n";
        sleep 10;

        # Return hashref or arrayref
        return { success => 1 };

    sub task_cb {
        my ($kernel, $heap, $request, $result) = @_[KERNEL, HEAP, ARG0, ARG1];

        print STDERR "Task with param ".$request->{params}[1]." returned "
            .($result->{success} ? 'successful' : 'failure')."\n";




Call ->create() like with any other POE::Session, passing a list of named parameters.

Session States

new_request (\%param)

The primary interface to enqueueing requests. Takes the following arguments in a hashref.

  $poe_kernel->post( PreforkDispatch => 'new_request', {
    method_name => 'do_something',
    params => [ 'Computer 3' ],

Request to response

After a new_request() is issued, the dispatcher will process it in a FIFO queue, using forks if available, or handling it synchronously otherwise. Handling a request is done by searching for a valid method, either picking the $request->{method}, or if not available, searching the dispatcher methods, classes and finally the xmlrpc_server_parent for something to handle $request->{method_name}.

If the method given is a subref, it will be passed ($from, @args). If a POE session state name, the calling session will have this state posted to with the same args ($from, @args):

  my ($from, @args) = @_;


  my ($kernel, $heap, $from, @args) = @_[KERNEL, HEAP, ARG0 .. $#_];

Once the request is handled, successfully or not, a response is sent to either the request's 'upon_result', or the dispatchers. If the method is a subref, it will be handed ($request, $response). Similar for session state. The request will be the same as passed, but with the additional key/value of 'elapsed' containing the seconds the request took to process. The response will be the response value of the method that handled the request, or in the case of an error, a hashref with the key 'error'.

Special methods

There are some methods that are special and can be used to control child fork behavior


POE, POE::Component::Pool::Thread, POE::Component::JobQueue



Eric Waters <>


Copyright (c) 2007 Eric Waters and XMission LLC ( All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

syntax highlighting: