File Coverage

blib/lib/POE/Component/Sequence/Nested.pm

Criterion	Covered	Total	%
statement	30	31	96.7
branch	8	10	80.0
condition	9	15	60.0
subroutine	5	5	100.0
pod			n/a
total	52	61	85.2

package POE::Component::Sequence::Nested;

=head1 NAME

POE::Component::Sequence::Nested - Adds special features to nested sequences

=head1 SYNOPSIS

    use POE qw(Component::Sequence::Nested);

    POE::Component::Sequence
        ->new(
            {
                auto_pause => 1,
                auto_resume => 1,
                merge_heap => 1,
            },
            sub {
                POE::Component::Sequence
                    ->new(
                        sub {
                            my $subseq = shift;
                            $subseq->heap_set(
                                a => 5,
                                b => 19,
                                op => '+',
                            );
                        },
                    )->run;
            },
            sub {
                my $sequence = shift;
                my $math = join ' ', map { $sequence->heap_index($_) } qw(a op b);
                $sequence->heap_set(result => eval $math);
            }
        )
        ->add_callback(sub {
            my ($sequence, $result) = @_;
            print "Answer was " . $sequence->heap_index('result') . "\n";
        })
        ->run();

=head1 DESCRIPTION

A nested sequence is one in which the return value of an action is another Sequence.  When this is the case, we can perform some automated tasks which save each action from redundant calls.

By itself it does nothing, but given any of the following actions, it will do it's magic:

=head2 auto_resume

=over 4

The parent sequence remains paused, but the child sequence has a callback added onto it which will resume the parent sequence:

  $child_sequence->add_callback(sub {
    $parent_sequence->resume;
  });

=back

=head2 auto_error

=over 4

This propogates a child sequence failure to the parent via $child->add_error_callback().  This would happen anyway if the child sequence throws an exception, but if the child sequence is already catching errors via another callback

=back

=head2 merge_heap

=over 4

The heap of the child sequence will be merged with the parent when it's complete:

  $child_sequence->add_finally_callback(sub {
    $parent_sequence->heap_set( $child_sequence->heap );
  });

This allows for shared heap access.

=back

=cut

use strict;
use warnings;
use POE::Component::Sequence;
use Scalar::Util qw(blessed);

BEGIN {
    unshift @POE::Component::Sequence::_plugin_handlers,
    sub {
        my ($self, $request) = @_;

        my $action = $request->{action};
        my $opt    = $request->{options};

        if (! defined $action || ! ref $action || ref $action ne 'CODE') {
            return { deferred => 1 };
        }

        my $return = $action->(@_);

        if ($return && ref $return && blessed $return
            && $return->isa('POE::Component::Sequence')) {
            if (delete $opt->{auto_resume}) {
                $return->add_finally_callback(sub {
                    $self->resume;
                });
            }
            if (delete $opt->{auto_error}) {
                $return->add_error_callback(sub {
                    $self->failed($_[1]);
                });
            }
            if (delete $opt->{merge_heap}) {
                $return->add_finally_callback(sub {
                    my %transaction_heap = $_[1]->heap;
                    $self->heap_set(%transaction_heap);
                });
            }
        }

        return { value => $return };
    };
}

1;

__END__