NAME

Async::Hooks::Ctl - Hook control object

VERSION

version 0.16

SYNOPSIS

    # inside a callback

    sub my_callback {
      my $ctl = shift;     # This is the Async::Hooks::Ctl object
      my $args = shift;    # Arguments for the hook

      $args = $ctl->args;  # Args are also available with the args() method

      return $ctl->done;          # no other callbacks are called
                           # ... or ...
      return $ctl->decline;       # call next callback
    }

DESCRIPTION

A Async::Hooks::Ctl object controls the sequence of invocation of callbacks.

Each callback receives two parameters: a Async::Hooks::Ctl object, and a arrayref with the hook arguments.

Each callback must call one of the sequence control methods before returning. Usually you just write:

    return $ctl->done();
    # ... or ...
    return $ctl->decline();

If you know what you are doing, you can also do this:

    $ctl->decline();
    # do other stuff here
    return;

But there are no guarantees that your code after the control method call will be run at the end of the callback sequence.

The important rule is that you must call one and only one of the control methods per callback.

The object provides two methods that control the invocation sequence, decline() and done(). The done() method will stop the sequence, and no other callback will be called. The decline() method will call the next callback in the sequence.

A cleanup callback can also be defined, and it will be called at the end of all callbacks, or imediatly after done(). This callback receives a third argument, a flag $is_done, that will be true if the chain ended with a call to done() or stop().

The decline() method can also be called as declined() or next(). The done() method can also be called as stop().

METHODS

CLASS->new($hooks, $args, $cleanup)

The new() constructor returns a Async::Hooks::Ctl object. All parameters are optional.

• $hooks

  An arrayref with all the callbacks to call.

• $args

  An arrayref with all the hook arguments.

• $cleanup

  A coderef with the cleanup callback to use.

$ctl->args()

Returns the hook arguments.

$ctl->decline()

Calls the next callback in the hook sequence.

If there are no callbacks remaining and if a cleanup callback was defined, it will be called with the $is_done flag as false.

$ctl->declined()

An alias to $ctl->decline().

$ctl->next()

An alias to $ctl->decline().

$ctl->done()

Stops the callback sequence. No other callbacks in the sequence will be called.

If a cleanup callback was defined, it will be called with the $is_done flag as true.

$ctl->stop()

An alias to $ctl->done().

AUTHOR

Pedro Melo <melo@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Pedro Melo.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)