NAME

POE::Component::PubSub - A publish/subscribe component for the POE framework

VERSION

version 0.091370

SYNOPSIS

      #imports PUBLISH_INPUT and PUBLISH_OUTPUT
      use POE::Component::PubSub;

      # Instantiate the publish/subscriber with the alias "pub"
      POE::Component::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

POE::Component::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.

CLASS METHODS

new(): This is the constructor for the publish subscribe component. It accepts the same arguments as any class composed with POEx::Role::SessionInstantiation.
See POEx::Role::SessionInstantiation for details.

ATTRIBUTES

_api_peek $pubsub->_api_peek

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

_events $pubsub->_events

This is a private attribute for accessing the PubSub::Events stored in this instance of PubSub. Contains a Set::Object as provided by MooseX::Types::Set::Object.

METHODS

_default(@args)

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.

destroy

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(SessionAlias :$session?, Str :$return_event?) returns (ArrayRef[POE::Component::PubSub::Event])

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(SessionAlias :$session?, Str :$event_name!, PublishType :$publish_type?, Str :$input_handler?)

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.

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(SessionAlias :$session?, Str :$event_name)

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

cancel(SessionAlias :$session?, Str :$event_name)

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

AUTHOR

  Nicholas Perez <nperez@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007