1POE::Loop(3) User Contributed Perl Documentation POE::Loop(3)
2
6 POE::Loop - documentation for POE's event loop bridge interface
7
9 $kernel->loop_initialize();
10 $kernel->loop_finalize();
11 $kernel->loop_do_timeslice();
12 $kernel->loop_run();
13 $kernel->loop_halt();
14 $kernel->loop_watch_signal($signal_name);
16 $kernel->loop_ignore_signal($signal_name);
17 $kernel->loop_attach_uidestroy($gui_window);
18 $kernel->loop_resume_time_watcher($next_time);
20 $kernel->loop_reset_time_watcher($next_time);
21 $kernel->loop_pause_time_watcher();
22 $kernel->loop_watch_filehandle($handle, $mode);
24 $kernel->loop_ignore_filehandle($handle, $mode);
25 $kernel->loop_pause_filehandle($handle, $mode);
26 $kernel->loop_resume_filehandle($handle, $mode);
27
29 POE::Loop is a virtual base class that defines a standard event loop
30 interface. POE::Loop subclasses mix into POE::Kernel and implement the
31 features needed to manage underlying event loops in a consistent
32 fashion. This documentation covers the interface, which is shared by
33 all subclasses.
34 As POE::Kernel loads, it searches through %INC for event loop modules.
36 POE::Kernel loads the most appropriate POE::Loop subclass for the event
37 loop it finds. The subclass slots its methods into POE::Kernel,
38 completing the class at load time. POE and POE::Kernel provide ways to
39 state the desired event loop in case the auto-detection makes a mistake
40 or the developer prefers to be explicit. See "Using POE with Other
41 Event Loops" in POE::Kernel for instructions on how to actually use POE
42 with other event loops, event loop naming conventions, and other
43 details.
44 POE::Loop subclasses exist for many of the event loops Perl supports:
46 select(), IO::Poll, WxWindows, EV, Glib, Event, and so on. See CPAN
47 for a full list.
48
50 As previously noted, POE::Loop subclasses provide additional methods to
51 POE::Kernel and are not proper objects in themselves.
52 Each POE::Loop subclass first defines its own namespace and version
54 within it. This way CPAN and other things can track its version. They
55 then switch to the POE::Kernel package to define their additional
56 methods.
57 POE::Loop is designed as a mix-in class because Perl imposed a
59 performance penalty for method inheritance at the time the class was
60 designed. This could be changed in the future, but it will require
61 cascaded changes in several other classes.
62 Here is a skeleton of a POE::Loop subclass:
64 use strict;
66 # YourToolkit bridge for POE::Kernel;
68 package POE::Loop::YourToolkit;
70 use vars qw($VERSION);
72 $VERSION = '1.000'; # NOTE - Should be #.### (three decimal places)
73 package POE::Kernel;
75 # Define private lexical data here.
77 # Implement the POE::Loop interface here.
78 1;
80 __END__
82 =head1 NAME
84 ... documentation goes here ...
86 =cut
88
90 POE::Loop's public interface is divided into four parts: administrative
91 methods, signal handler methods, time management methods, and
92 filehandle watcher methods. Each group and its members will be
93 described in detail shortly.
94 POE::Loop subclasses use lexical variables to keep track of things.
96 Exact implementation is left up to the subclass' author.
97 POE::Loop::Select keeps its bit vectors for select() calls in class-
98 scoped (static) lexical variables. POE::Loop::Gtk tracks a single time
99 watcher and multiple file watchers there.
100 Bridges often employ private methods as callbacks from their event
102 loops. The Event, Gtk, and Tk bridges do this. Private callback names
103 should begin with "_loop_" to avoid colliding with other methods.
104 Developers should look at existing bridges to get a feel for things.
106 The "-m" flag for perldoc will show a module in its entirety.
107 perldoc -m POE::Loop::Select
109 perldoc -m POE::Loop::Gtk
110 ...
111 Administrative Methods
113 These methods initialize and finalize an event loop, run the loop to
114 process events, and halt it.
115 loop_initialize
117 Initialize the event loop. Graphical toolkits especially need some
119 sort of init() call or sequence to set up. For example, Tk requires a
120 widget to be created before any events will be processed, and the
121 program's user interface will be considered destroyed if that widget is
122 closed.
123 sub loop_initialize {
125 my $self = shift;
126 $poe_main_window = Tk::MainWindow->new();
128 die "could not create a main Tk window" unless defined $poe_main_window;
129 $self->signal_ui_destroy($poe_main_window);
130 }
131 POE::Loop::Select initializes its select() bit vectors.
133 sub loop_initialize {
135 @loop_vectors = ( '', '', '' );
136 vec($loop_vectors[MODE_RD], 0, 1) = 0;
137 vec($loop_vectors[MODE_WR], 0, 1) = 0;
138 vec($loop_vectors[MODE_EX], 0, 1) = 0;
139 }
140 loop_finalize
142 Finalize the event loop. Most event loops do not require anything here
144 since they have already stopped by the time loop_finalize() is called.
145 However, this is a good place to check that a bridge has not leaked
146 memory or data. This example comes from POE::Loop::Event.
147 sub loop_finalize {
149 my $self = shift;
150 foreach my $fd (0..$#fileno_watcher) {
152 next unless defined $fileno_watcher[$fd];
153 foreach my $mode (MODE_RD, MODE_WR, MODE_EX) {
154 POE::Kernel::_warn(
155 "Mode $mode watcher for fileno $fd is defined during loop finalize"
156 ) if defined $fileno_watcher[$fd]->[$mode];
157 }
158 }
159 $self->loop_ignore_all_signals();
161 }
162 loop_do_timeslice
164 Wait for time to pass or new events to occur, and dispatch any events
166 that become due. If the underlying event loop does this through
167 callbacks, then loop_do_timeslice() will either provide minimal glue or
168 do nothing.
169 For example, loop_do_timeslice() for POE::Loop::Select sets up and
171 calls select(). If any files or other resources become active, it
172 enqueues events for them. Finally, it triggers dispatch for any events
173 are due.
174 On the other hand, the Gtk event loop handles all this, so
176 loop_do_timeslice() is empty for the Gtk bridge.
177 A sample loop_do_timeslice() implementation is not presented here
179 because it would either be quite large or empty. See each
180 POE::Loop::IO_Poll or Select for large ones. Event and Gtk are empty.
181 The bridges for Poll and Select for large ones. The ones for Event and
183 Gtk are empty, and Tk's (in POE::Loop::TkCommon) is rather small.
184 loop_run
186 Run an event loop until POE has no more sessions to handle events.
188 This method tends to be quite small, and it is often implemented in
189 terms of loop_do_timeslice(). For example, POE::Loop::IO_Poll
190 implements it:
191 sub loop_run {
193 my $self = shift;
194 while ($self->_data_ses_count()) {
195 $self->loop_do_timeslice();
196 }
197 }
198 This method is even more trivial when an event loop handles it. This
200 is from the Gtk bridge:
201 sub loop_run {
203 unless (defined $_watcher_timer) {
204 $_watcher_timer = Gtk->idle_add(\&_loop_resume_timer);
205 }
206 Gtk->main;
207 }
208 loop_halt
210 loop_halt() does what it says: It halts POE's underlying event loop.
212 It tends to be either trivial for external event loops or empty for
213 ones that are implemented in the bridge itself (IO_Poll, Select).
214 For example, the loop_run() method in the Poll bridge exits when
216 sessions have run out, so its loop_halt() method is empty:
217 sub loop_halt {
219 # does nothing
220 }
221 Gtk, however, needs to be stopped because it does not know when POE is
223 done.
224 sub loop_halt {
226 Gtk->main_quit();
227 }
228 Signal Management Methods
230 These methods enable and disable signal watchers. They are used by
231 POE::Resource::Signals to manage an event loop's signal watchers.
232 Most event loops use Perl's %SIG to watch for signals. This is so
234 common that POE::Loop::PerlSignals implements the interface on behalf
235 of other subclasses.
236 loop_watch_signal SIGNAL_NAME
238 Watch for a given SIGNAL_NAME. SIGNAL_NAME is the version found in
240 %SIG, which tends to be the operating signal's name with the leading
241 "SIG" removed.
242 POE::Loop::PerlSignals' implementation adds callbacks to %SIG except
244 for CHLD/CLD, which begins a waitpid() polling loop instead.
245 As of this writing, all of the POE::Loop subclasses register their
247 signal handlers through POE::Loop::PerlSignals.
248 There are three types of signal handlers:
250 CHLD/CLD handlers, when managed by the bridges themselves, poll for
252 exited children. POE::Kernel does most of this, but
253 loop_watch_signal() still needs to start the process.
254 PIPE handlers. The PIPE signal event must be sent to the session that
256 is active when the signal occurred.
257 Everything else. Signal events for everything else are sent to
259 POE::Kernel, where they are distributed to every session.
260 The loop_watch_signal() methods tends to be very long, so an example is
262 not presented here. The Event and Select bridges have good examples,
263 though.
264 loop_ignore_signal SIGNAL_NAME
266 Stop watching SIGNAL_NAME. POE::Loop::PerlSignals does this by
268 resetting the %SIG for the SIGNAL_NAME to a sane value.
269 $SIG{CHLD} is left alone so as to avoid interfering with system() and
271 other things.
272 SIGPIPE is generally harmless since POE generates events for this
274 condition. Therefore $SIG{PIPE} is set to "IGNORE" when it's not being
275 handled.
276 All other signal handlers default to "DEFAULT" when not in use.
278 loop_attach_uidestroy WIDGET
280 POE, when used with a graphical toolkit, should shut down when the user
282 interface is closed. loop_attach_uidestroy() is used to shut down POE
283 when a particular WIDGET is destroyed.
284 The shutdown is done by firing a UIDESTROY signal when the WIDGET's
286 closure or destruction callback is invoked. UIDESTROY guarantees the
287 program will shut down by virtue of being terminal and non-maskable.
288 loop_attach_uidestroy() is only meaningful in POE::Loop subclasses that
290 tie into user interfaces. All other subclasses leave the method empty.
291 Here's Gtk's:
293 sub loop_attach_uidestroy {
295 my ($self, $window) = @_;
296 $window->signal_connect(
297 delete_event => sub {
298 if ($self->_data_ses_count()) {
299 $self->_dispatch_event(
300 $self, $self,
301 EN_SIGNAL, ET_SIGNAL, [ 'UIDESTROY' ],
302 __FILE__, __LINE__, undef, time(), -__LINE__
303 );
304 }
305 return 0;
306 }
307 );
308 }
309 Alarm and Time Management Methods
311 These methods enable and disable a time watcher or alarm in the
312 underlying event loop. POE only requires one, which is reused or re-
313 created as necessary.
314 Most event loops trigger callbacks when time has passed. It is the
316 bridge's responsibility to register and unregister a callback as
317 needed. When invoked, the callback should dispatch events that have
318 become due and possibly set up a new callback for the next event to be
319 dispatched.
320 The time management methods may accept NEXT_EVENT_TIME. This is the
322 time the next event will become due, in UNIX epoch time.
323 NEXT_EVENT_TIME is a real number and may have sub-second accuracy. It
324 is the bridge's responsibility to convert this value into something the
325 underlying event loop requires.
326 loop_resume_time_watcher NEXT_EVENT_TIME
328 Resume an already active time watcher. It is used with
330 loop_pause_time_watcher() to provide less expensive timer toggling for
331 frequent use cases. As mentioned above, NEXT_EVENT_TIME is in UNIX
332 epoch time and may have sub-second accuracy.
333 loop_resume_time_watcher() is used by bridges that set them watchers in
335 the underlying event loop. For example, POE::Loop::Gtk implements it
336 this way:
337 sub loop_resume_time_watcher {
339 my ($self, $next_time) = @_;
340 $next_time -= time();
341 $next_time *= 1000;
342 $next_time = 0 if $next_time < 0;
343 $_watcher_timer = Gtk->timeout_add(
344 $next_time, \&_loop_event_callback
345 );
346 }
347 This method is usually empty in bridges that implement their own event
349 loops.
350 loop_reset_time_watcher NEXT_EVENT_TIME
352 Reset a time watcher, often by stopping or destroying an existing one
354 and creating a new one in its place. It is often a wrapper for
355 loop_resume_time_watcher() that first destroys an existing watcher.
356 For example, POE::Loop::Gkt's implementation:
357 sub loop_reset_time_watcher {
359 my ($self, $next_time) = @_;
360 Gtk->timeout_remove($_watcher_timer);
361 undef $_watcher_timer;
362 $self->loop_resume_time_watcher($next_time);
363 }
364 loop_pause_time_watcher
366 Pause a time watcher without destroying it, if the underlying event
368 loop supports such a thing. POE::Loop::Event does support it:
369 sub loop_pause_time_watcher {
371 $_watcher_timer or return;
372 $_watcher_timer->stop();
373 }
374 File Activity Management Methods
376 These methods enable and disable file activity watchers. There are
377 four methods: loop_watch_filehandle(), loop_ignore_filehandle(),
378 loop_pause_filehandle(), and loop_resume_filehandle(). The "pause" and
379 "resume" methods are lightweight versions of "ignore" and "watch",
380 respectively.
381 All the methods take the same two parameters: a file HANDLE and a file
383 access MODE. Modes may be MODE_RD, MODE_WR, or MODE_EX. These
384 constants are defined by POE::Kernel and correspond to the semantics of
385 POE::Kernel's select_read(), select_write(), and select_expedite()
386 methods.
387 POE calls MODE_EX "expedited" because it often signals that a file is
389 ready for out-of-band information. Not all event loops handle MODE_EX.
390 For example, Tk:
391 sub loop_watch_filehandle {
393 my ($self, $handle, $mode) = @_;
394 my $fileno = fileno($handle);
395 my $tk_mode;
397 if ($mode == MODE_RD) {
398 $tk_mode = 'readable';
399 }
400 elsif ($mode == MODE_WR) {
401 $tk_mode = 'writable';
402 }
403 else {
404 # The Tk documentation implies by omission that expedited
405 # filehandles aren't, uh, handled. This is part 1 of 2.
406 confess "Tk does not support expedited filehandles";
407 }
408 # ... rest omitted ....
410 }
411 loop_watch_filehandle FILE_HANDLE, IO_MODE
413 Watch a FILE_HANDLE for activity in a given IO_MODE. Depending on the
415 underlying event loop, a watcher or callback will be registered for the
416 FILE_HANDLE. Activity in the specified IO_MODE (read, write, or out of
417 band) will trigger emission of the proper event in application space.
418 POE::Loop::Select sets the fileno()'s bit in the proper select() bit
420 vector. It also keeps track of which file descriptors are active.
421 sub loop_watch_filehandle {
423 my ($self, $handle, $mode) = @_;
424 my $fileno = fileno($handle);
425 vec($loop_vectors[$mode], $fileno, 1) = 1;
426 $loop_filenos{$fileno} |= (1<<$mode);
427 }
428 loop_ignore_filehandle FILE_HANDLE, IO_MODE
430 Stop watching the FILE_HANDLE in a given IO_MODE. Stops (and possibly
432 destroys) an event watcher corresponding to the FILE_HANDLE and
433 IO_MODE.
434 POE::Loop::IO_Poll's loop_ignore_filehandle() manages descriptor/mode
436 bits for its _poll() method here. It also performs some cleanup if a
437 descriptor is no longer being watched after this ignore call.
438 sub loop_ignore_filehandle {
440 my ($self, $handle, $mode) = @_;
441 my $fileno = fileno($handle);
442 my $type = mode_to_poll($mode);
444 my $current = $poll_fd_masks{$fileno} || 0;
445 my $new = $current & ~$type;
446 if (TRACE_FILES) {
448 POE::Kernel::_warn(
449 sprintf(
450 "<fh> Ignore $fileno: " .
451 ": Current mask: 0x%02X - removing 0x%02X = 0x%02X\n",
452 $current, $type, $new
453 )
454 );
455 }
456 if ($new) {
458 $poll_fd_masks{$fileno} = $new;
459 }
460 else {
461 delete $poll_fd_masks{$fileno};
462 }
463 }
464 loop_pause_filehandle FILE_HANDLE, IO_MODE
466 This is a lightweight form of loop_ignore_filehandle(). It is used
468 along with loop_resume_filehandle() to temporarily toggle a watcher's
469 state for a FILE_HANDLE in a particular IO_MODE.
470 Some event loops, such as Event.pm, support their file watchers being
472 disabled and re-enabled without the need to destroy and re-create the
473 watcher objects.
474 sub loop_pause_filehandle {
476 my ($self, $handle, $mode) = @_;
477 my $fileno = fileno($handle);
478 $fileno_watcher[$fileno]->[$mode]->stop();
479 }
480 By comparison, Event's loop_ignore_filehandle() method cancels and
482 destroys the watcher object.
483 sub loop_ignore_filehandle {
485 my ($self, $handle, $mode) = @_;
486 my $fileno = fileno($handle);
487 if (defined $fileno_watcher[$fileno]->[$mode]) {
488 $fileno_watcher[$fileno]->[$mode]->cancel();
489 undef $fileno_watcher[$fileno]->[$mode];
490 }
491 }
492 Ignoring and re-creating watchers is relatively expensive, so
494 POE::Kernel's select_pause_read() and select_resume_read() methods (and
495 the corresponding ones for write and expedite) use the faster versions.
496 loop_resume_filehandle FILE_HANDLE, IO_MODE
498 This is a lightweight form of loop_watch_filehandle(). It is used
500 along with loop_pause_filehandle() to temporarily toggle a a watcher's
501 state for a FILE_HANDLE in a particular IO_MODE.
502
504 This is a rehash of "Using POE with Other Event Loops" in POE::Kernel.
505 Firstly, if a POE::Loop subclass is manually loaded before POE::Kernel,
507 then that will be used. End of story.
508 If one isn't, POE::Kernel searches for an external event loop module in
510 %INC. For each module in %INC, corresponding POE::XS::Loop and
511 POE::Loop subclasses are tried.
512 For example, if IO::Poll is loaded, POE::Kernel tries
514 use POE::XS::Loop::IO_Poll;
516 use POE::Loop::IO_Poll;
517 This is relatively expensive, but it ensures that POE::Kernel can find
519 new POE::Loop subclasses without defining them in a central registry.
520 POE::Loop::Select is the fallback event loop. It's loaded if no other
522 event loop can be found in %INC.
523 It can't be repeated often enough that event loops must be loaded
525 before POE::Kernel. Otherwise they will not be present in %INC, and
526 POE::Kernel will not detect them.
527
529 POE, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
530 POE::Loop::Select, POE::Loop::Tk.
531 POE::Test::Loops is POE's event loop tests released as a separate,
533 reusable distribution. POE::Loop authors are encouraged to use the
534 tests for their own distributions.
535 TODO - Link to CPAN for POE::Loop modules.
537
539 TODO - Link to POE bug queue.
540
542 Please see POE for more information about authors, contributors, and
543 POE's licensing.
544perl v5.12.1 2010-04-03 POE::Loop(3)