/ 
POEx-PubSub-1.102740
/ POEx::PubSub

NAME

POEx::PubSub - A second generation publish/subscribe component for the POE framework

VERSION

version 1.102740

SYNOPSIS

#imports PUBLISH_INPUT and PUBLISH_OUTPUT
use POEx::PubSub;

# Instantiate the publish/subscriber with the alias "pub"
POEx::PubSub->new(alias => 'pub');

# Publish an event called "FOO". +PUBLISH_OUTPUT is actually optional.
$_[KERNEL]->post
(
    'pub', 
    'publish', 
    event_name => 'FOO', 
    publish_type => +PUBLISH_OUTPUT
);

# Elsewhere, subscribe to that event, giving it an event to call
# when the published event is fired.
$_[KERNEL]->post
(
    'pub', 
    'subscribe', 
    event_name => 'FOO', 
    event_handler => 'FireThisEvent'
);

# Fire off the published event
$_[KERNEL]->post('pub', 'FOO');

# Publish an 'input' event
$_[KERNEL]->post
(
    'pub', 
    'publish', 
    event_name => 'BAR', 
    publish_type => +PUBLISH_INPUT, 
    input_handler =>'MyInputEvent'
);

# Publish an event for another session
$_[KERNEL]->post
(
    'pub',
    'publish',
    session => 'other_session',
    event_name => 'SomeEvent',
);

# Subscribe to an event for another session
$_[KEREL]->post
(
    'pub',
    'publish,
    session => 'other_session',
    event_name => 'SomeEvent',
    event_handler => 'other_sessions_handler',
);

# Tear down the whole thing
$_[KERNEL]->post('pub', 'destroy');

DESCRIPTION

POEx::PubSub provides a publish/subscribe mechanism for the POE framework allowing sessions to publish events and to also subscribe to those events. Firing a published event posts an event to each subscriber of that event. Publication and subscription can also be managed from an external session, but defaults to using the SENDER where possible.

PRIVATE_ATTRIBUTES

_api_peek

is: ro, isa: class_type('POE::API::Peek')

This is a private attribute for accessing POE::API::Peek.

_events

This is a private attribute for accessing the PubSub::Events stored in this instance of PubSub keyed by the event name. If events need to be accessed please use the provided methods: { all_events => 'values', add_event => 'set', remove_event => 'delete', get_event => 'get', has_events => 'count', }

PUBLIC_METHODS

destroy

is Event

This event will simply destroy any of its current events and remove any and all aliases this session may have picked up. This should free up the session for garbage collection.

listing

(SessionRefIdAliasInstantiation :$session?, Str :$return_event?) is Event returns (ArrayRef)

To receive a listing of all the of the events inside of PubSub, you can either call this event and have it returned immediately, or return_event must be provided and implemented in either the provided session or SENDER and the only argument to the return_event will be the events.

publish

(SessionRefIdAliasInstantiation :$session?, Str :$event_name!, PublishType :$publish_type?, Str :$input_handler?) is Event

This is the event to use to publish events. The published event may not already be previously published. The event may be completely arbitrary and does not require the publisher to implement that event. Think of it as a name for a mailing list.

You can also publish an 'input' or inverse event. This allows for arbitrary sessions to post to your event. In this case, you must supply the optional published event type and the event to be called when the published event fires.

There are two types: PUBLISH_INPUT and PUBLISH_OUTPUT. PUBLISH_OUPUT is implied when no argument is supplied.

Also, you can publish an event from an arbitrary session as long as you provide a session alias.

subscribe

(SessionRefIdAliasInstantiation :$session?, Str :$event_name, Str :$event_handler) is Event

This event is used to subscribe to a published event. The event does not need to exist at the time of subscription to avoid chicken and egg scenarios. The event_handler must be implemented in either the provided session or in the SENDER.

rescind

(SessionRefIdAliasInstantiation :$session?, Str :$event_name) is Event

Use this event to stop publication of an event. The event must be published by either the provided session or SENDER

cancel

(SessionRefIdAliasInstantiation :$session?, Str :$event_name) is Event

Cancel subscriptions to events with this event. The event must contain the provided session or SENDER as a subscriber

PRIVATE_METHODS

_default

(ArrayRef $args) is Event

After an event is published, the publisher may arbitrarily fire that event to this component and the subscribers will be notified by calling their respective return events with whatever arguments are passed by the publisher. The event must be published, owned by the publisher, and have subscribers for the event to be propagated. If any of the subscribers no longer has a valid return event their subscriptions will be cancelled and a warning will be carp'd.

This overrides POEx::Role::SessionInstantiation::_default().

_has_event(SessionID :$session, Str :$event_name)

This is a private method used by PubSub to confirm the session has the stated event. If it is class that composed SessionInstantiation, it checks via MOP, otherwise it uses POE::API::Peek to accomplis the deed.

AUTHOR

Nicholas Perez <nperez@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Nicholas Perez.

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