1POE::Wheel(3)         User Contributed Perl Documentation        POE::Wheel(3)
2
3
4

NAME

6       POE::Wheel - event-driven mixins for POE::Session
7

SYNOPSIS

9       This base class has no synopsis.  Please consult one of the subclasses
10       instead.
11

DESCRIPTION

13       A POE::Wheel object encapsulates a bundle of event handlers that
14       perform a specific task.  It also manages the event watchers that
15       trigger those handlers.
16
17       Object lifetime is very important for POE wheels.  At creation time,
18       most wheels will add anonymous event handlers to the currently active
19       session.  In other words, the session that created the wheel is
20       modified to handle new events.  Event watchers may also be initialized
21       as necessary to trigger the new handlers.  These event watchers are
22       also owned by the session that created the wheel.
23
24       Sessions must not expose their wheels to other sessions.  Doing so will
25       likely cause problems because wheels are tightly integrated with the
26       sessions that created them.  For example, calling put() on a
27       POE::Wheel::ReadWrite instance may enable a write-okay watcher.  The
28       handler for this watcher is already defined in the wheel's owner.
29       Calling put() outside that session will enable the write-okay watcher
30       in the wrong session, and the event will never be handled.
31
32       Likewise, wheels must be destroyed from within their creator sessions.
33       Otherwise breakage will occur when the wheels' DESTROY methods try to
34       unregister event handlers and watchers from the wrong sessions.  To
35       simplify things, it's recommended to store POE::Wheel instances in
36       heaps of the sessions that created them.
37
38       For example, creating a POE::Wheel::FollowTail object will register an
39       event handler that periodically polls a file for new information.  It
40       will also start the timer that triggers the periodic polling.
41
42         use POE;
43         use POE::Wheel::FollowTail;
44
45         my @files_to_tail = qw( messages maillog security );
46
47         foreach my $filename (@files_to_tail) {
48           POE::Session->create(
49             inline_states => {
50               _start => sub {
51                 push @{$_[HEAP]{messages}}, POE::Wheel::FollowTail->new(
52                   Filename   => "/var/log/$filename",
53                   InputEvent => "got_input",
54                 );
55               },
56               got_input => sub {
57                 print "$filename: $_[ARG0]\n";
58               },
59             }
60           );
61         }
62
63         POE::Kernel->run();
64         exit;
65
66       As illustrated in the previous example it is possible---sometimes
67       recommended---to create more than one POE::Wheel of a particular type
68       in the same session.  A session with multiple wheels may scale better
69       than separate sessions with one wheel apiece.  When in doubt,
70       benchmark.
71
72       Unlike components (or cheese), wheels do not stand alone.  Each wheel
73       must be created by a session in order to register event watchers and
74       handlers within that session.  Wheels are thusly tightly coupled to
75       their creator sessions and cannot be passed to other sessions.
76

FILTERS, AND DRIVERS

78       Many wheels perform data transfer operations on filehandles (which, as
79       you probably know, includes sockets, pipes, and just about anything
80       else that can store or transfer data).
81
82       To avoid subclass hell, POE::Wheel objects may be customized at
83       creation time by including other objects from the POE::Filter and
84       POE::Driver namespaces.
85
86   Filters
87       POE "filters" implement data parsers and serializers.  For example,
88       POE::Filter::Line parses streams into records separated by some string
89       (the traditional network newline by default).  The Line filter also
90       adds record separators to data being output.
91
92       POE::Filter::HTTPD is a more complex example.  It implements a subset
93       of the server-side of the HTTP protocol.  Input streams are parsed into
94       HTTP requests and wrapped in HTTP::Request objects.  Server code sends
95       HTTP::Response objects back to the client, which are serialized so they
96       may be sent to a socket.
97
98       Most wheels use POE::Filter::Line by default.
99
100   Drivers
101       POE "drivers" implement strategies for sending data to a filehandle and
102       receiving input from it.  A single POE::Wheel class may interact with
103       files, pipes, sockets, or devices by using the appropriate driver.
104
105       POE::Driver::SysRW is the only driver that comes with POE.  sysread()
106       and syswrite() can handle nearly every kind of stream interaction, so
107       there hasn't been much call for another type of driver.
108

METHODS

110       POE::Wheel defines a common interface that most subclasses use.
111       Subclasses may implement other methods, especially to help perform
112       their unique tasks.  If something useful isn't documented here, see the
113       subclass before implementing a feature.
114
115   Required Methods
116       These methods are required by all subclasses.
117
118       new LOTS_OF_STUFF
119
120       new() instantiates and initializes a new wheel object and returns it.
121       The new wheel will continue to function for as long as it exists,
122       although other methods may alter the way it functions.
123
124       Part of any wheel's construction is the registration of anonymous event
125       handlers to perform wheel-specific tasks.  Event watchers are also
126       started to trigger the handlers when relevant activity occurs.
127
128       Every wheel has a different purpose and requires different constructor
129       parameters, so LOTS_OF_STUFF is documented in each particular subclass.
130
131       DESTROY
132
133       DESTROY is Ye Olde Perl Object Destructor.  When the wheel's last
134       strong reference is relinquished, DESTROY triggers the wheel's cleanup.
135       The object removes itself from the session that created it: Active
136       event watchers are stopped, and anonymous event handlers are
137       unregistered.
138
139       event EVENT_TYPE, EVENT_NAME [, EVENT_TYPE, EVENT_NAME, ....]
140
141       event() changes the events that a wheel will emit.  Its parameters are
142       one or more pairs of EVENT_TYPEs and the EVENT_NAMEs to emit when each
143       type of event occurs.  If an EVENT_NAME is undefined, then the wheel
144       will stop emitting that type of event.  Or the wheel may throw an error
145       if the event type is required.
146
147       EVENT_TYPEs differ for each wheel and correspond to the constructor
148       parameters that match /.*Event$/.  For example, POE::Wheel::ReadWrite
149       may emit up to five different kinds of event: InputEvent, ErrorEvent,
150       FlushedEvent, HighEvent, LowEvent.  The name of each emitted event may
151       be changed at run time.
152
153       This example changes the events to emit on new input and when output is
154       flushed.  It stops the wheel from emitting events when errors occur.
155
156         $wheel->event(
157           InputEvent   => 'new_input_event',
158           ErrorEvent   => undef,
159           FlushedEvent => 'new_flushed_event',
160         );
161
162   I/O Methods
163       Wheels that perform input and output may implement some or all of these
164       methods.  The put() method is a common omission.  Wheels that don't
165       perform output do not have put() methods.
166
167       put RECORD [, RECORD [, ....]]
168
169       put() sends one or more RECORDs to the wheel for transmitting.  Each
170       RECORD is serialized by the wheel's associated POE::Filter so that it
171       will be ready to transmit.  The serialized stream may be transmitted
172       immediately by the wheel's POE::Driver object, or it may be buffered in
173       the POE::Driver until it can be flushed to the output filehandle.
174
175       Most wheels use POE::Filter::Line and POE::Driver::SysRW by default, so
176       it's not necessary to specify them in most cases.
177
178   Class Static Functions
179       These functions expose information that is common to all wheels.  They
180       are not methods, so they should not be called as methods.
181
182         my $new_wheel_id = POE::Wheel::allocate_wheel_id();
183         POE::Wheel::free_wheel_id($new_wheel_id);
184
185       allocate_wheel_id
186
187       This is not a class method.
188
189       Every wheel has a unique ID.  allocate_wheel_id() returns the next
190       available unique wheel ID.  Wheel constructors use it to set their IDs
191       internally.
192
193         package POE::Wheel::Example;
194         use base qw(POE::Wheel);
195
196         sub new {
197           # ... among other things ...
198           $self->[MY_WHEEL_ID] = POE::Wheel::allocate_wheel_id();
199           return $self;
200         }
201
202       Wheel IDs are used to tell apart events from similarly typed wheels.
203       For example, a multi-file tail utility may handle all file input with
204       the same function.  Wheel IDs may be used to tell which wheel generated
205       the InputEvent being handled.
206
207       Wheel IDs are often used to store wheel-local state in a session's
208       heap.
209
210         sub handle_error {
211           my $wheel_id = $_[ARG3];
212           print "Wheel $wheel_id caught an error.  Shutting it down.\n";
213           delete $_[HEAP]{wheels}{$wheel_id};
214         }
215
216       It is vital for wheels to free their allocated IDs when they are
217       destroyed.  POE::Wheel class keeps track of allocated wheel IDs to
218       avoid collisions, and they will remain in memory until freed.  See
219       free_wheel_id().
220
221       free_wheel_id WHEEL_ID
222
223       This is not a class method.
224
225       free_wheel_id() deallocates a wheel's ID so that it stops consuming
226       memory and may be reused later.  This is often called from a wheel's
227       destructor.
228
229         package POE::Wheel::Example;
230         use base qw(POE::Wheel);
231
232         sub DESTROY {
233           my $self = shift;
234           # ... among other things ...
235           POE::Wheel::free_wheel_id($self->[MY_WHEEL_ID]);
236         }
237
238       Wheel IDs may be reused, although it has never been reported.  Two
239       active wheels will never share the same ID, however.
240
241       ID
242
243       This is usually implemented in the subclass!
244
245       The ID() method returns a wheel's unique ID. It is commonly used to
246       match events with the wheels which generated them.
247
248       Again, this method is not implemented in this class! If it's missing
249       from the subclass, please go pester that module author---thanks!
250

SEE ALSO

252       The SEE ALSO section in POE contains a table of contents covering the
253       entire POE distribution.
254
255       POE::Driver - A base class for file access drivers that POE::Wheel may
256       use.
257
258       POE::Filter - A base class for data parsers and marshalers that
259       POE::Wheel may use.
260
261       POE::Wheel::Curses - Non-blocking input for Curses.
262
263       POE::Wheel::FollowTail - Non-blocking file and FIFO monitoring.
264
265       POE::Wheel::ListenAccept - Non-blocking server for existing sockets.
266
267       POE::Wheel::ReadLine - Non-blocking console input, with full readline
268       support.
269
270       POE::Wheel::ReadWrite - Non-blocking stream I/O.
271
272       POE::Wheel::Run - Non-blocking process creation and management.
273
274       POE::Wheel::SocketFactory - Non-blocking socket creation, supporting
275       most protocols and modes.
276
277       TODO - Link to POE::Wheel search.cpan.org module search.
278

BUGS

280       It would be nice if wheels were more like proper Unix streams.
281

AUTHORS & COPYRIGHTS

283       Please see POE for more information about authors, contributors, and
284       POE;s licensing.
285
286
287
288perl v5.12.1                      2010-04-03                     POE::Wheel(3)
Impressum