NAME

Event::Wrappable - Sugar to let you instrument event listeners at a distance

VERSION

version 0.1.1

SYNOPSIS

    use Event::Wrappable;
    use AnyEvent;
    use AnyEvent::Collect;
    my @wrappers = (
        sub {
            my( $event ) = @_;
            return sub { say "Calling event..."; $event->(); say "Done with event" };
        },
    );

    my($w1,$w2);
    # Collect just waits till all the events registered in its block fire
    # before returning.
    collect {
        Event::Wrappable->wrap_events( sub {
            $w1 = AE::timer 0.1, 0, event { say "First timer triggered" };
        }, @wrappers );
        $w2 = AE::timer 0.2, 0, event { say "Second timer triggered" };
    };

    # Will print:
    #     Calling event...
    #     First timer triggered
    #     Done with event
    #     Second timer triggered

    # The below does the same thing, but using method handlers instead.

    use MooseX::Declare;
    class ExampleClass {
        method listener_a {
            say "First timer event handler";
        }
        method listener_b {
            say "Second timer event handler";
        }
    }

    collect {
        my $listeners = ExampleClass->new;
        Event::Wrappable->wrap_events( sub {
            $w1 = AE::timer 0.1, 0, event_method $listeners=>"listener_a";
        }, @wrappers );
        $w2 = AE::timer 0.2, 0, event_method $listeners=>"listener_b";
    };

DESCRIPTION

This is a helper for creating globally wrapped events listeners. This is a way of augmenting all of the event listeners registered during a period of time. See AnyEvent::Collect and MooseX::Event for examples of its use.

A lexically scoped variant might be desirable, however I'll have to explore the implications of that for my own use cases first.

CLASS METHODS

method wrap_events( CodeRef $code, @wrappers )

Adds @wrappers to the event wrapper list for the duration of $code.

   Event::Wrappable->wrap_events(sub { setup_some_events() }, sub { wrapper() });

This change to the wrapper list is dynamically scoped, so any events registered by functions you call will be wrapped as well.

method get_wrappers() returns Array|ArrayRef

In list context returns an array of the current event wrappers. In scalar context returns an arrayref of the wrappers used on this event.

METHODS

method get_unwrapped() returns CodeRef

Returns the original, unwrapped event handler from the wrapped version.

method get_wrappers() returns Array|ArrayRef

In list context returns an array of the wrappers used on this event. In scalar context returns an arrayref of the wrappers used on this event.

method object_id() returns Int

Returns an invariant unique identifier for this event. This will not change even across threads and is suitable for hashing based on an event.

HELPERS

sub event( CodeRef $code ) returns CodeRef

Returns the wrapped code ref, to be passed to be an event listener. This code ref will be blessed as Event::Wrappable.

sub event_method( $object, $method ) returns CodeRef

Returns a wrapped code ref suitable for use in an event listener. The code ref basically the equivalent of:

    sub { $object->$method(@_) }

Except faster and without the anonymous wrapper sub in the call stack. Method lookup is done when you register the event, which means that if you can't apply any roles to the object after you register event listeners using it.

SOURCE

The development version is on github at http://https://github.com/iarna/Event-Wrappable and may be cloned from git://https://github.com/iarna/Event-Wrappable.git

SUPPORT

Websites

More information can be found at:

• MetaCPAN

  A modern, open-source CPAN search engine, useful to view POD in HTML format.

  http://metacpan.org/release/Event-Wrappable

Bugs / Feature Requests

Please report any bugs at https://github.com/iarna/Event-Wrappable/issues.

AUTHOR

Rebecca Turner <becca@referencethis.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Rebecca Turner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Event::Wrappable

perl -MCPAN -e shell
install Event::Wrappable