Debian Codegraph @

README

raw
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