| 1 |
NAME |
| 2 |
POE::Component::PubSub - A generic publish/subscribe POE::Component that |
| 3 |
enables POE::Sessions to publish events to which other POE::Sessions may |
| 4 |
subscribe. |
| 5 |
|
| 6 |
VERSION |
| 7 |
Version 0.04 |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
# Instantiate the publish/subscriber with the alias "pub" |
| 11 |
POE::Component::PubSub->new('pub'); |
| 12 |
|
| 13 |
# Publish an event called "FOO". +PUBLISH_OUTPUT is actually optional. |
| 14 |
$_[KERNEL]->post('pub', 'publish', 'FOO', +PUBLISH_OUTPUT); |
| 15 |
|
| 16 |
# Elsewhere, subscribe to that event, giving it an event to call # when |
| 17 |
the published event is fired. $_[KERNEL]->post('pub', 'subscribe', |
| 18 |
'FOO', 'FireThisEvent'); |
| 19 |
|
| 20 |
# Fire off the published event $_[KERNEL]->post('pub', 'FOO'); |
| 21 |
|
| 22 |
# Publish an 'input' event $_[KERNEL]->post('pub', 'publish', 'BAR', |
| 23 |
+PUBLISH_INPUT, 'MyInputEvent'); |
| 24 |
|
| 25 |
# Tear down the whole thing $_[KERNEL]->post('pub', 'destroy'); |
| 26 |
|
| 27 |
EVENTS |
| 28 |
All public events do some sanity checking to make sure of a couple of |
| 29 |
things before allowing the events such as checking to make sure the |
| 30 |
posting session actually owns the event it is publishing, or that the |
| 31 |
event passed as the return event during subscription is owned by the |
| 32 |
sender. When one of those cases comes up, an error is carp'd, and the |
| 33 |
event returns without stopping execution. |
| 34 |
|
| 35 |
'publish' |
| 36 |
This is the event to use to publish events. It accepts one argument, |
| 37 |
the event to publish. The published event may not already be |
| 38 |
previously published. The event may be completely arbitrary and does |
| 39 |
not require the publisher to implement that event. Think of it as a |
| 40 |
name for a mailing list. |
| 41 |
|
| 42 |
You can also publish an 'input' or inverse event. This allows for |
| 43 |
arbitrary sessions to post to your event. In this case, you must |
| 44 |
supply the optional published event type and the event to be called |
| 45 |
when the published event fires. |
| 46 |
|
| 47 |
There are two types: PUBLISH_INPUT and PUBLISH_OUTPUT. PUBLISH_OUPUT |
| 48 |
is implied when no argument is supplied. |
| 49 |
|
| 50 |
'subscribe' |
| 51 |
This is the event to use when subscribing to published events. It |
| 52 |
accepts two arguments: 1) the published event, and 2) the event name |
| 53 |
of the subscriber to be called when the published event is fired. |
| 54 |
The event doesn't need to be published prior to subscription to |
| 55 |
resolve chicken and egg problems in an async environment. But, the |
| 56 |
sender must own and implement the return event. |
| 57 |
|
| 58 |
'rescind' |
| 59 |
Use this event to stop publication of an event. It accepts one |
| 60 |
argument, the published event. The event must be published, and |
| 61 |
published by the sender of the rescind event. If the published event |
| 62 |
has any subscribers, a warning will be carp'd but execution will |
| 63 |
continue. |
| 64 |
|
| 65 |
'cancel' |
| 66 |
Cancel subscriptions to events with this event. It accepts one |
| 67 |
argment, the published event. The event must be published and the |
| 68 |
sender must be subscribed to the event. |
| 69 |
|
| 70 |
'_default' |
| 71 |
After an event is published, the publisher may arbitrarily fire that |
| 72 |
event to this component and the subscribers will be notified by |
| 73 |
calling their respective return events with whatever arguments are |
| 74 |
passed by the publisher. The event must be published, owned by the |
| 75 |
publisher, and have subscribers for the event to be propagated. If |
| 76 |
any of the subscribers no longer has a valid return event their |
| 77 |
subscriptions will be cancelled and a warning will be carp'd. |
| 78 |
|
| 79 |
'listing' |
| 80 |
To receive an array reference containing tuples of the event name, |
| 81 |
and the type of the events that are currently published within the |
| 82 |
component, call this event. It accepts one argument, the return |
| 83 |
event to fire with the listing. The sender must own the return |
| 84 |
event. |
| 85 |
|
| 86 |
'destroy' |
| 87 |
This event will simply destroy any of its current state and remove |
| 88 |
any and all aliases this session may have picked up. This should |
| 89 |
free up the session for garbage collection. |
| 90 |
|
| 91 |
CLASS METHODS |
| 92 |
POE::Component::PubSub->new($alias) |
| 93 |
This is the constructor for the publish subscribe component. It |
| 94 |
instantiates it's own session using the provided $alias argument to |
| 95 |
set its kernel alias. If no alias is provided, the default alias is |
| 96 |
'PUBLISH_SUBSCRIBE'. |
| 97 |
|
| 98 |
DEBUGGING |
| 99 |
$POE::Component::PubSub::TRACE_AND_DEBUG |
| 100 |
To enable debugging within the component at the POE::Session level |
| 101 |
and also with various warnings, set this variable to logical true |
| 102 |
BEFORE calling new(). |
| 103 |
|
| 104 |
NOTES |
| 105 |
Right now this component is extremely simple, but thorough when it comes |
| 106 |
to checking the various requirements for publishing and subscribing. |
| 107 |
Currently, there is no mechanism to place meta-subscriptions to the |
| 108 |
events of the component itself. This feature is planned for the next |
| 109 |
release. |
| 110 |
|
| 111 |
Also, to do some of the checking on whether subscribers own the return |
| 112 |
events, some ideas were lifted from POE::API::Peek, and like that |
| 113 |
module, if there are changes to the POE core, they may break this |
| 114 |
module. |
| 115 |
|
| 116 |
AUTHOR |
| 117 |
Nicholas R. Perez, "<nperez at cpan.org>" |
| 118 |
|
| 119 |
BUGS |
| 120 |
Please report any bugs or feature requests to "bug-poe-component-pubsub |
| 121 |
at rt.cpan.org", or through the web interface at |
| 122 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-PubSub>. I |
| 123 |
will be notified, and then you'll automatically be notified of progress |
| 124 |
on your bug as I make changes. |
| 125 |
|
| 126 |
SUPPORT |
| 127 |
You can find documentation for this module with the perldoc command. |
| 128 |
|
| 129 |
perldoc POE::Component::PubSub |
| 130 |
|
| 131 |
You can also look for information at: |
| 132 |
|
| 133 |
* AnnoCPAN: Annotated CPAN documentation |
| 134 |
|
| 135 |
<http://annocpan.org/dist/POE-Component-PubSub> |
| 136 |
|
| 137 |
* CPAN Ratings |
| 138 |
|
| 139 |
<http://cpanratings.perl.org/d/POE-Component-PubSub> |
| 140 |
|
| 141 |
* RT: CPAN's request tracker |
| 142 |
|
| 143 |
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-PubSub> |
| 144 |
|
| 145 |
* Search CPAN |
| 146 |
|
| 147 |
<http://search.cpan.org/dist/POE-Component-PubSub> |
| 148 |
|
| 149 |
COPYRIGHT & LICENSE |
| 150 |
Copyright 2008-2009 Nicholas R. Perez, all rights reserved. |
| 151 |
|
| 152 |
This program is released under the following license: gpl |
| 153 |
|