Async-Hooks
view release on metacpan or search on metacpan
* Dzil-ify the distribution
0.05 Mon Mar 23 17:50:12 WET 2009
* Added has_hooks_for($hook) method
0.04 Sat Mar 21 15:20:33 WET 2009
* Added $is_done flag to cleanup callback
0.03 Sat Mar 21 14:46:36 WET 2009
* Make sure our versions have two digits
* Fix: chain run was clearing all callbacks
0.02 Thu Mar 19 18:49:39 WET 2009
* Fixed Moose tests when the Moose is missing
0.01 Wed Mar 18 13:05:02 WET 2009
* First version, released on an unsuspecting world.
lib/Async/Hooks.pm view on Meta::CPAN
});
=head1 DESCRIPTION
This module allows you to create hooks on your own modules that other
developers can use to extend your functionality, or just react to
important state modifications.
There are other modules that provide the same functionality (see
L<SEE ALSO> section). The biggest diference is that you can pause
processing of the chain of callbacks at any point and start a
asynchronous network request, and resume processing when that request
completes.
Developers are not expect to subclass from C<Async::Hooks>. The
recomended usage is to stick a C<Async::Hooks> instance in a slot or as
a singleton for your whole app, and then delegate some methods to it.
For example, using L<Moose|Moose> you can just:
has 'hooks' => (
lib/Async/Hooks.pm view on Meta::CPAN
There are two main usages for hooks: notification or delegation of
responsability.
You can define hook points for notification of important events inside
your class. For example, if you where writting a feed aggregator, you
could define a hook for notification of new items.
In some other cases, your module wants to make part of its bussiness
logic extendable or even replaceable. For example, a SMTP server can ask
if a specific mail address is a valid RCPT. All the registered callbacks
would be called and if one of them has a definitive answer she can just
stop the chain. You can even define a default callback to be called at
the end, as a cleanup step.
You don't need to pre-declare or create a hook. Clients of your module
should consult your documentation to discover which hooks to you support
and then they should just call the C<hook()> method. It takes two
parameters: a scalar, the hook name, and a coderef, the callback.
To call the hook chain, you use the C<call()> method. It requires a
scalar, the hook to call, as the first parameter. The second
optional parameter is an arrayref with arguments, or undef. The third
optional argument, a coderef, is a cleanup callback. This callback
will be called at the end of the chain or as soon as some callback
ends the chain.
The callbacks all have a common signature. They receive two parameters.
The first one is a L<Async::Hooks::Ctl|Async::Hooks::Ctl> object, used
to control the chain of callbacks. The second is an arrayref with the
arguments you used when the hook was called. Something like this:
sub my_callback {
my ($ctl, $args) = @_;
....
}
A third parameter is passed to the cleanup callback: a C<$is_done> flag,
with a true value if the chain was ended prematurely C<done()> or
C<stop()>.
The callback only has one responsability: decide if you want to decline
processing of this event, or stop processing if we are done with it.
Cleanup callbacks I<MUST> just return.
To do that, callbacks must call one of two methods:
C<< $ctl->decline() >> or C<< $ctl->done() >>. You can also use
C<next()> or C<declined()> as alias to C<decline()>, and C<stop()>
as alias to C<done()>, whatever feels better.
But you can delay that decision. You can start a network request,
asynchronously, and only decide to decline or stop when the response
arrives. For example, if you use the L<AnyEvent::HTTP|AnyEvent::HTTP>
module to make a HTTP request, you could do something like this:
sub check_server_is_up_cb {
lib/Async/Hooks.pm view on Meta::CPAN
=item $registry->call($hook_name [, \@args] [, \&cleanup])
Calls a specific hook name chain. You can optionally provide an arrayref
with arguments that each callback will receive.
The optional cleanup callback will be called at the end of the chain, or
when a callback calls C<< $ctl->done() >>.
=item $count = $registry->has_hooks_for($hook);
Returns the number of callbacks registered with C<$hook>.
=back
=head1 SEE ALSO
There are a couple of modules that do similar things to this one:
=over 4
=item * L<Object::Event|Object::Event>
lib/Async/Hooks/Ctl.pm view on Meta::CPAN
=head1 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
}
=head1 DESCRIPTION
A C<Async::Hooks::Ctl> object controls the sequence of invocation of
callbacks.
Each callback receives two parameters: a C<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();
lib/Async/Hooks/Ctl.pm view on Meta::CPAN
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,
C<decline()> and C<done()>. The C<done()> method will stop the sequence,
and no other callback will be called. The C<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 C<done()>. This callback receives a
third argument, a flag C<$is_done>, that will be true if the chain
ended with a call to C<done()> or C<stop()>.
The C<decline()> method can also be called as C<declined()> or
C<next()>. The C<done()> method can also be called as C<stop()>.
=head1 METHODS
=over
=item CLASS->new($hooks, $args, $cleanup)
The C<new()> constructor returns a C<Async::Hooks::Ctl> object. All
parameters are optional.
=over
=item * $hooks
An arrayref with all the callbacks to call.
=item * $args
An arrayref with all the hook arguments.
=item * $cleanup
A coderef with the cleanup callback to use.
=back
=item $ctl->args()
Returns the hook arguments.
=item $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 C<$is_done> flag as false.
=item $ctl->declined()
An alias to C<< $ctl->decline() >>.
=item $ctl->next()
An alias to C<< $ctl->decline() >>.
=item $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
C<$is_done> flag as true.
=item $ctl->stop()
An alias to C<< $ctl->done() >>.
=back
( run in 1.216 second using v1.01-cache-2.11-cpan-9b1e4054eb1 )