1POE::Wheel(3) User Contributed Perl Documentation POE::Wheel(3)
2
6 POE::Wheel - event-driven mixins for POE::Session
7
9 This base class has no synopsis. Please consult one of the subclasses
10 instead.
11
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 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 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 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 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 use POE;
43 use POE::Wheel::FollowTail;
44 my @files_to_tail = qw( messages maillog security );
46 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 POE::Kernel->run();
64 exit;
65 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 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
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 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 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 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 Most wheels use POE::Filter::Line by default.
99 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 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
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 Required Methods
116 These methods are required by all subclasses.
117 new LOTS_OF_STUFF
119 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 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 Every wheel has a different purpose and requires different constructor
129 parameters, so LOTS_OF_STUFF is documented in each particular subclass.
130 DESTROY
132 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 event EVENT_TYPE, EVENT_NAME [, EVENT_TYPE, EVENT_NAME, ....]
140 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 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 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 $wheel->event(
157 InputEvent => 'new_input_event',
158 ErrorEvent => undef,
159 FlushedEvent => 'new_flushed_event',
160 );
161 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 put RECORD [, RECORD [, ....]]
168 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 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 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 my $new_wheel_id = POE::Wheel::allocate_wheel_id();
183 POE::Wheel::free_wheel_id($new_wheel_id);
184 allocate_wheel_id
186 This is not a class method.
188 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 package POE::Wheel::Example;
194 use base qw(POE::Wheel);
195 sub new {
197 # ... among other things ...
198 $self->[MY_WHEEL_ID] = POE::Wheel::allocate_wheel_id();
199 return $self;
200 }
201 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 Wheel IDs are often used to store wheel-local state in a session's
208 heap.
209 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 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 free_wheel_id WHEEL_ID
222 This is not a class method.
224 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 package POE::Wheel::Example;
230 use base qw(POE::Wheel);
231 sub DESTROY {
233 my $self = shift;
234 # ... among other things ...
235 POE::Wheel::free_wheel_id($self->[MY_WHEEL_ID]);
236 }
237 Wheel IDs may be reused, although it has never been reported. Two
239 active wheels will never share the same ID, however.
240 ID
242 This is usually implemented in the subclass!
244 The ID() method returns a wheel's unique ID. It is commonly used to
246 match events with the wheels which generated them.
247 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
252 The SEE ALSO section in POE contains a table of contents covering the
253 entire POE distribution.
254 POE::Driver - A base class for file access drivers that POE::Wheel may
256 use.
257 POE::Filter - A base class for data parsers and marshalers that
259 POE::Wheel may use.
260 POE::Wheel::Curses - Non-blocking input for Curses.
262 POE::Wheel::FollowTail - Non-blocking file and FIFO monitoring.
264 POE::Wheel::ListenAccept - Non-blocking server for existing sockets.
266 POE::Wheel::ReadLine - Non-blocking console input, with full readline
268 support.
269 POE::Wheel::ReadWrite - Non-blocking stream I/O.
271 POE::Wheel::Run - Non-blocking process creation and management.
273 POE::Wheel::SocketFactory - Non-blocking socket creation, supporting
275 most protocols and modes.
276
278 It would be nice if wheels were more like proper Unix streams.
279
281 Please see POE for more information about authors, contributors, and
282 POE;s licensing.
283perl v5.36.0 2023-01-20 POE::Wheel(3)