Async-Hooks

 view release on metacpan or  search on metacpan

META.json  view on Meta::CPAN

{
   "abstract" : "Hook system with asynchronous capabilities",
   "author" : [
      "Pedro Melo <melo@cpan.org>"
   ],
   "dynamic_config" : 0,
   "generated_by" : "Dist::Zilla version 4.300002, CPAN::Meta::Converter version 2.112621",
   "license" : [
      "artistic_2"
   ],
   "meta-spec" : {
      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",

META.yml  view on Meta::CPAN

---
abstract: 'Hook system with asynchronous capabilities'
author:
  - 'Pedro Melo <melo@cpan.org>'
build_requires:
  Test::Deep: 0
  Test::Fatal: 0
  Test::More: 0.98
configure_requires:
  ExtUtils::MakeMaker: 6.30
dynamic_config: 0
generated_by: 'Dist::Zilla version 4.300002, CPAN::Meta::Converter version 2.112621'

Makefile.PL  view on Meta::CPAN

use strict;
use warnings;



use ExtUtils::MakeMaker 6.30;



my %WriteMakefileArgs = (
  "ABSTRACT" => "Hook system with asynchronous capabilities",
  "AUTHOR" => "Pedro Melo <melo\@cpan.org>",
  "BUILD_REQUIRES" => {
    "Test::Deep" => 0,
    "Test::Fatal" => 0,
    "Test::More" => "0.98"
  },
  "CONFIGURE_REQUIRES" => {
    "ExtUtils::MakeMaker" => "6.30"
  },
  "DISTNAME" => "Async-Hooks",

README  view on Meta::CPAN

This archive contains the distribution Async-Hooks,
version 0.16:

  Hook system with asynchronous capabilities

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

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

lib/Async/Hooks.pm  view on Meta::CPAN

package Async::Hooks;
{
  $Async::Hooks::VERSION = '0.16';
}

# ABSTRACT: Hook system with asynchronous capabilities

use Mo qw(is default);
use Carp 'confess';
use Async::Hooks::Ctl;
use namespace::clean;


has registry => (
  is      => 'ro',
  default => sub { {} },

lib/Async/Hooks.pm  view on Meta::CPAN

1;    # End of Async::Hooks


__END__
=pod

=head1 NAME

Async::Hooks - Hook system with asynchronous capabilities

=head1 VERSION

version 0.16

=head1 SYNOPSIS

    use Async::Hooks;

    my $nc = Async::Hooks->new;

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' => (
      isa     => 'Async::Hooks',

lib/Async/Hooks.pm  view on Meta::CPAN

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 {
      my ($ctl, $args) = @_;
      my ($url) = @$args;

      http_get($url, sub {
        my ($data, $headers) = @_;

lib/Async/Hooks.pm  view on Meta::CPAN

=item * L<Class::Observable|Class::Observable>

=item * L<Event::Notify|Event::Notify>

=item * L<Notification::Center|Notification::Center>

=back

Of those four, only L<Object::Event|Object::Event> version 1.0 and later
provides the same ability to pause a chain, do some asynchrounous work
and resume chain processing later.

=head1 ACKNOWLEDGEMENTS

The code was inspired by the C<run_hook_chain> and C<hook_chain_fast>
code of the L<DJabberd project|DJabberd> (see the
L<DJabberd::VHost|DJabberd::VHost> module source code). Hat tip to Brad
Fitzpatrick.

=head1 AUTHOR