View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Joe Vannucci > Parallel-Fork-BossWorkerAsync-0.06 > Parallel::Fork::BossWorkerAsync



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.06   Source   Latest Release: Parallel-Fork-BossWorkerAsync-0.09


Parallel::Fork::BossWorkerAsync - Perl extension for creating asynchronous forking queue processing applications.


  use Parallel::Fork::BossWorkerAsync ();
  my $bw = Parallel::Fork::BossWorkerAsync->new(
    work_handler    => \&work,
    result_handler  => \&handle_result,
    global_timeout  => 2,

  # Jobs are hashrefs
  $bw->add_work( {a => 3, b => 4} );
  while ($bw->pending()) {
    my $ref = $bw->get_result();
    if ($ref->{ERROR}) {
      print STDERR $ref->{ERROR};
    } else {
      print "$ref->{product}\n";
      print "$ref->{string}\n";

  sub work {
    my ($job)=@_;

    # Uncomment to test timeout
    # sleep(3);
    # Uncomment to test worker error
    # die("rattle");
    # do something with hash ref $job
    my $c = $job->{a} * $job->{b};
    # Return values are hashrefs
    return { product => $c };

  sub handle_result {
    my ($result)=@_;
    if (exists($result->{product})) {
      $result->{string} = "the answer is: $result->{product}";
    return $result;

  the answer is: 12


Parallel::Fork::BossWorkerAsync implements a multiprocess preforking server. On construction, the current process forks a "Boss" process (the server), which then forks one or more "Worker" processes. The Boss acts as a manager, accepting jobs from the main process, queueing and passing them to the next available idle Worker. The Boss then listens for, and collects any responses from the Workers as they complete jobs, queueing them for the main process. At any time, the main process can collect available responses from the Boss.

Having a separate Boss process allows the main application to behave asynchronously with respect to the queued work. Also, since the Boss is acting as a server, the application can send it more work at any time.



Creates and returns a new Parallel::Fork::BossWorkerAsync object.

  my $bw = Parallel::Fork::BossWorkerAsync->new(
    work_handler    => \&work_sub,
    result_handler  => \&result_sub,
    init_handler    => \&init_sub,
    global_timeout  => 0,
    worker_count    => 3,
    msg_delimiter   => "\0\0\0"


Adds work to the instance's queue. It accepts a list of hash refs. add_work() can be called at any time before shut_down(). All work can be added at the beginning, and then the results gathered, or these can be interleaved: add a few jobs, grab the results of one of them, add a few more, grab more results, etc.

Note: Jobs are not guaranteed to be processed in the order they're added. This is because they are farmed out to multiple workers running concurrently.

  $bw->add_work({data => "my data"}, {data => "more stuff"}, ...);


This simple function returns a true value if there are jobs that have been submitted for which the results have not yet been retrieved.

Note: This says nothing about the readiness of the results. Just that at some point, now or in the future, the results will be available for collection.

  while ($bw->pending()) { }


Requests the next single available job result from the Boss' result queue. Returns the return value of the work_handler. If there is a result_handler defined, it's called here, and the return value of this function is returned instead. Return from either function is expected to be a hashref. Depending on what your work_handler, or result_handler, does, it may not be interesting to capture this result.

By default, get_result() is a blocking call. If there are no completed job results available, main application processing will stop here and wait.

  my $href = $bw->get_result();

If you want nonblocking behavior:

  my $href = $bw->get_result( blocking => 0 );
  my $href = $bw->get_result_nb();

In this case, if the call would block, because there is no result to retrieve, it returns immediately, returning undef.


Tells the Boss and all Workers to exit. All results should have been retrieved via get_result() prior to calling shut_down(). If shut_down() is called earlier, the queue *will* be processed, but depending on timing the subsequent calls to get_result() may fail if the boss has already written all result data into the socket buffer and exited.


If you just want the Boss and Workers to go away, and don't care about work in progress, use:

  $bw->shut_down( force => 1 );

Error handling ^

Errors generated by your work_handler do not cause the worker process to die. These are stuffed in the result hash with a key of 'ERROR'. The value is $@.

If global_timeout is set, and a timeout occurs, the worker returns: { ERROR => 'BossWorkerAsync: timed out' }


Parallel::Fork::BossWorkerAsync received inspiration from Parallel::Fork::BossWorker. The main difference is that BossWorkerAsync introduces the Boss as a separate process, a bi-directional multiplexing, listening, queueing, server. This allows the calling process much more freedom in interacting with, or ignoring, the Boss.


Please report bugs to

Forked processes and threads don't mix well. It's a good idea to construct Parallel::Fork::BossWorkerAsync before multiple threads are created.

This module will probably not work on Windows due to its reliance on UNIX IPC mechanisms.


Thanks to Jeff Rodriguez for his module Parallel::Fork::BossWorker.


Copyright (C) 2009 by joe vannucci, <>

All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: