NAME

POE::Component::StackedProcessor - Stacked Processors In POE

SYNOPSIS

  use POE::Component::StackedProcessor;
  POE::Component::StackedProcessor->new(
    Alias      => $alias,
    Processors => [ $proc1, $proc2, $proc3 ],
    InlineStates => {  # or PackageStates/ObjectStates
      success => \&success_cb,
      failure => \&failure_cb
    }
  );
  POE::Kernel->run();

  # else where in the code...
  $kernel->post($alias, 'process', 'success', 'failure', $input);

DESCRIPTION

POE::Component::StackedProcessor allows you to build a chain of processors whose dispatching depends on the successful completion of the previous processor.

For example, suppose you have an HTML document that requires you to verify whethere it meats certain criteria such as proper markup, valid links, etc. Normally this would be done in one pass for the sake of efficiency, but sometimes you want to break these steps up into several components such that you can mix and match the differnt processors as required.

The basic steps to creating a stacked processor is as follows:

1. Create some processors

These are just simple objects that have a method called "process". The method should take exactly one parameter, which is the "thing" being processed, whatever it may be. It must return a true value upon successful execution. If an exception is thrown or the method returns a false value, the processing is terminated right there and then, and the failure event will be called.

Once you define these processors, pass them to the Processors argument to new(), in the order that you want them executed:

  POE::Component::StackedProcessor->new(
    ...
    Processors => [ $p1, $p2, $p3 ... ]
  );

2. Define success and failure events

You need to define success and failure events so that upon completion of executing the processors, you can do some post processing. You specify which states get called.

  # Calling from outside a POE session:
  sub success_cb { ... }
  sub failure_cb { ... }
  POE::Component::StackedProcessor->new(
    ...,
    InlineStates => {  # or PackageStates/ObjectStates
      success => \&success_cb,
      failure => \&failure_cb
    }
  );

Because the success/failure events are invoked via POE::Kernel's post() method, they will receive the "request" and "response" arguments in ARG0 and ARG1, which are arrayrefs:

  sub success_cb {
    my($response, $response) = @_[ARG0, ARG1];
    # whatever that got passed to process() is in $response-E<gt>[0];
    ...
  }

3. Send some data to be processed

Once you've set up the processors and the success/failure states, send some data to the StackedProcessor session via POE::Kernel->post()

  POE::Kernel->post(
    $alias_of_stacked_processor,
    'process', # this is always the same
    $success_event,
    $failure_event,
    $arg_to_process
  );

If all processors complete execution successfully, $success_event will be called. Otherwise $failure_event gets called.

METHODS

new ARGS

Alias

Alias of the StackedProcessor session. (You probably want to set this, because you will need to post() to this session to run the processors)

Processors

An arrayref of processor objects. Each of these object must have a method denoted by "callback_name" (which is by default "process")

InlineStates/Packagestates/ObjectStates

Optional states to faciliate your method dispatching. You can, for example, set success and failure states there that gets called upon successful execution.

callback_name

This is a class-method to specify at run time what method name should be called on the processor objects. The default is "process".

SEE ALSO

POE

AUTHOR

Daisuke Maki <dmaki@cpan.org>