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

NAME

6       POE::Loop - documentation for POE's event loop bridge interface
7

SYNOPSIS

9         $kernel->loop_initialize();
10         $kernel->loop_finalize();
11         $kernel->loop_do_timeslice();
12         $kernel->loop_run();
13         $kernel->loop_halt();
14
15         $kernel->loop_watch_signal($signal_name);
16         $kernel->loop_ignore_signal($signal_name);
17         $kernel->loop_attach_uidestroy($gui_window);
18
19         $kernel->loop_resume_time_watcher($next_time);
20         $kernel->loop_reset_time_watcher($next_time);
21         $kernel->loop_pause_time_watcher();
22
23         $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

DESCRIPTION

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
35       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
45       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

GENERAL NOTES

50       As previously noted, POE::Loop subclasses provide additional methods to
51       POE::Kernel and are not proper objects in themselves.
52
53       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
58       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
63       Here is a skeleton of a POE::Loop subclass:
64
65         use strict;
66
67         # YourToolkit bridge for POE::Kernel;
68
69         package POE::Loop::YourToolkit;
70
71         use vars qw($VERSION);
72         $VERSION = '1.000'; # NOTE - Should be #.### (three decimal places)
73
74         package POE::Kernel;
75
76         # Define private lexical data here.
77         # Implement the POE::Loop interface here.
78
79         1;
80
81         __END__
82
83         =head1 NAME
84
85         ... documentation goes here ...
86
87         =cut
88

PUBLIC INTERFACE

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
95       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
101       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
105       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
108         perldoc -m POE::Loop::Select
109         perldoc -m POE::Loop::Gtk
110         ...
111
112   Administrative Methods
113       These methods initialize and finalize an event loop, run the loop to
114       process events, and halt it.
115
116       loop_initialize
117
118       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
124         sub loop_initialize {
125           my $self = shift;
126
127           $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
132       POE::Loop::Select initializes its select() bit vectors.
133
134         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
141       loop_finalize
142
143       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
148         sub loop_finalize {
149           my $self = shift;
150
151           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
160           $self->loop_ignore_all_signals();
161         }
162
163       loop_do_timeslice
164
165       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
170       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
175       On the other hand, the Gtk event loop handles all this, so
176       loop_do_timeslice() is empty for the Gtk bridge.
177
178       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
182       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
185       loop_run
186
187       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
192         sub loop_run {
193           my $self = shift;
194           while ($self->_data_ses_count()) {
195             $self->loop_do_timeslice();
196           }
197         }
198
199       This method is even more trivial when an event loop handles it.  This
200       is from the Gtk bridge:
201
202         sub loop_run {
203           unless (defined $_watcher_timer) {
204             $_watcher_timer = Gtk->idle_add(\&_loop_resume_timer);
205           }
206           Gtk->main;
207         }
208
209       loop_halt
210
211       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
215       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
218         sub loop_halt {
219           # does nothing
220         }
221
222       Gtk, however, needs to be stopped because it does not know when POE is
223       done.
224
225         sub loop_halt {
226           Gtk->main_quit();
227         }
228
229   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
233       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
237       loop_watch_signal SIGNAL_NAME
238
239       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
243       POE::Loop::PerlSignals' implementation adds callbacks to %SIG except
244       for CHLD/CLD, which begins a waitpid() polling loop instead.
245
246       As of this writing, all of the POE::Loop subclasses register their
247       signal handlers through POE::Loop::PerlSignals.
248
249       There are three types of signal handlers:
250
251       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
255       PIPE handlers.  The PIPE signal event must be sent to the session that
256       is active when the signal occurred.
257
258       Everything else.  Signal events for everything else are sent to
259       POE::Kernel, where they are distributed to every session.
260
261       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
265       loop_ignore_signal SIGNAL_NAME
266
267       Stop watching SIGNAL_NAME.  POE::Loop::PerlSignals does this by
268       resetting the %SIG for the SIGNAL_NAME to a sane value.
269
270       $SIG{CHLD} is left alone so as to avoid interfering with system() and
271       other things.
272
273       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
277       All other signal handlers default to "DEFAULT" when not in use.
278
279       loop_attach_uidestroy WIDGET
280
281       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
285       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
289       loop_attach_uidestroy() is only meaningful in POE::Loop subclasses that
290       tie into user interfaces.  All other subclasses leave the method empty.
291
292       Here's Gtk's:
293
294         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, monotime(), -__LINE__
303                 );
304               }
305               return 0;
306             }
307           );
308         }
309
310   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
315       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
321       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
327       loop_resume_time_watcher NEXT_EVENT_TIME
328
329       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
334       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
338         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
348       This method is usually empty in bridges that implement their own event
349       loops.
350
351       loop_reset_time_watcher NEXT_EVENT_TIME
352
353       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
358         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
365       loop_pause_time_watcher
366
367       Pause a time watcher without destroying it, if the underlying event
368       loop supports such a thing.  POE::Loop::Event does support it:
369
370         sub loop_pause_time_watcher {
371           $_watcher_timer or return;
372           $_watcher_timer->stop();
373         }
374
375   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
382       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
388       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
392         sub loop_watch_filehandle {
393           my ($self, $handle, $mode) = @_;
394           my $fileno = fileno($handle);
395
396           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
409           # ... rest omitted ....
410         }
411
412       loop_watch_filehandle FILE_HANDLE, IO_MODE
413
414       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
419       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
422         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
429       loop_ignore_filehandle FILE_HANDLE, IO_MODE
430
431       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
435       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
439         sub loop_ignore_filehandle {
440           my ($self, $handle, $mode) = @_;
441           my $fileno = fileno($handle);
442
443           my $type = mode_to_poll($mode);
444           my $current = $poll_fd_masks{$fileno} || 0;
445           my $new = $current & ~$type;
446
447           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
457           if ($new) {
458             $poll_fd_masks{$fileno} = $new;
459           }
460           else {
461             delete $poll_fd_masks{$fileno};
462           }
463         }
464
465       loop_pause_filehandle FILE_HANDLE, IO_MODE
466
467       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
471       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
475         sub loop_pause_filehandle {
476           my ($self, $handle, $mode) = @_;
477           my $fileno = fileno($handle);
478           $fileno_watcher[$fileno]->[$mode]->stop();
479         }
480
481       By comparison, Event's loop_ignore_filehandle() method cancels and
482       destroys the watcher object.
483
484         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
493       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
497       loop_resume_filehandle FILE_HANDLE, IO_MODE
498
499       This is a lightweight form of loop_watch_filehandle().  It is used
500       along with loop_pause_filehandle() to temporarily toggle a watcher's
501       state for a FILE_HANDLE in a particular IO_MODE.
502

HOW POE FINDS EVENT LOOP BRIDGES

504       This is a rehash of "Using POE with Other Event Loops" in POE::Kernel.
505
506       Firstly, if a POE::Loop subclass is manually loaded before POE::Kernel,
507       then that will be used.  End of story.
508
509       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
513       For example, if IO::Poll is loaded, POE::Kernel tries
514
515         use POE::XS::Loop::IO_Poll;
516         use POE::Loop::IO_Poll;
517
518       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
521       POE::Loop::Select is the fallback event loop.  It's loaded if no other
522       event loop can be found in %INC.
523
524       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

SEE ALSO

529       POE, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
530       POE::Loop::Select, POE::Loop::Tk.
531
532       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

BUGS

537       None known.
538

AUTHORS & LICENSING

540       Please see POE for more information about authors, contributors, and
541       POE's licensing.
542
543
544
545perl v5.38.0                      2023-07-21                      POE::Loop(3)
Impressum