NAME

Proc::tored::Pool::Manager - OO interface to creating a managed worker pool service

VERSION

version 0.07

SYNOPSIS

  use Proc::tored::Pool::Manager;

  my $manager = Proc::tored::Pool::Manager->new(
    name => 'thing-doer',
    dir => '/var/run',
    workers => 8,
    on_assignment => sub {
      my ($self, $id) = @_;
      ...
    },
    on_success => sub {
      my ($self, $id, @results) = @_;
      ...
    },
    on_failure => sub {
      my ($self, $id, $error) = @_;
      ...
    },
  );

  # Submit tasks to the pool
  $manager->service(sub {
    my ($thing_id, $thing) = next_thing();
    $manager->assign(sub { do_stuff_with($thing) }, $thing_id);
  });

  # Wait for all pending tasks to complete
  $manager->sync;

DESCRIPTION

The Manager is the object created "pool" in Proc::tored::Pool. It extends Proc::tored::Manager.

ATTRIBUTES

workers

Specifies the size of the pool of forked processes. Processes are forked as needed and used only once.

on_assignment

A code ref that is called when a task has been submitted to the worker pool. Receives the manager instance and the task id if submitted. to "assign".

on_success

A code ref that is triggered when a task's result has been collected. Receives the manager instance, the task id (if submitted), and any return value(s) from the submitted code block. If no values were returned from the code block, the results will be an empty list.

  Proc::tored::Manager->new(
    ...
    on_success => sub {
      my ($me, $id, @results) = @_;
      if (@results) {
        ...
      }
    },
  );

If the code ref passed to "assign" performs an exec, the results array will be replaced with zero-but-true when the worker process exits with a zero exit status. This is to (attempt to) avoid confusion in code where an assigned task may or may not exec.

  on_success => sub {
    my ($me, $id, @results) = @_;

    # Task exited cleanly but without a return value
    if (@results == 1 && $results->[0]) {
      ...
    }
  }

on_failure

A code ref that is triggered when a task died during execution or exited abnormally. Receives the manager instance, the task id (if submitted), and the error message.

pending

Returns the number of tasks that have been submitted but whose results have not yet been collected.

assign

Submits a task (a CODE ref) to the worker pool, optionally accepting a task id (something string-like).

sync

Blocks until all submitted tasks have completed and their results have been collected.

AUTHOR

Jeff Ober <jeffober@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Jeff Ober.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Proc::tored::Pool

perl -MCPAN -e shell
install Proc::tored::Pool