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's runtime kernel abstraction uses the "bridge" pattern to encapsu‐
30 late services provided by different event loops. This abstraction
31 allows POE to cooperate with several event loops and support new ones
32 with a minimum amount of work.
33 POE relies on a relatively small number of event loop services: signal
35 callbacks, time or alarm callbacks, and filehandle activity callbacks.
36 The rest of the bridge interface is administrative trivia such as ini‐
38 tializing, executing, and finalizing event loop.
39 POE::Kernel uses POE::Loop classes internally as a result of detecting
41 which event loop is loaded before POE is. You should almost never need
42 to "use" a POE::Loop class directly, although there is some early sup‐
43 port for doing so in cases where it's absolutely necessary.
44 See "Using POE with Other Event Loops" in POE::Kernel for details about
46 actually using POE with other event loops.
47
49 An event loop bridge is not a proper object in itself. Rather, it is a
50 suite of functions that are defined within the POE::Kernel namespace.
51 A bridge is a plugged-in part of POE::Kernel itself. Its functions are
52 proper POE::Kernel methods.
53 Each bridge first defines its own namespace and version within it.
55 This way CPAN and other things can track its version.
56 # $Id: Loop.pm 2116 2006-09-08 04:45:45Z rcaputo $
58 use strict;
60 # YourToolkit bridge for POE::Kernel;
62 package POE::Loop::YourToolkit;
64 use vars qw($VERSION);
66 $VERSION = do {my@r=(q$Revision: 2116 $=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
67 package POE::Kernel;
69 ... private lexical data and functions defined here ...
71 1;
73 __END__
75 =head1 NAME
77 ... documentation goes here ...
79 =cut
81 The public interface for loop bridges is broken into four parts: admin‐
83 istrative functions, signal functions, time functions, and filehandle
84 functions. They will be described in detail shortly.
85 Bridges use lexical variables to keep track of things. The types and
87 number of variables depends on the needs of each event loop. For exam‐
88 ple, POE::Loop::Select keeps bit vectors for its select() call.
89 POE::Loop::Gtk tracks a single time watcher and multiple file watchers
90 for each file descriptor.
91 Bridges often employ private functions as callbacks from their event
93 loops. The Event, Gtk, and Tk bridges do this.
94 Developers should look at existing bridges to get a feel for things.
96 The "-m" flag for perldoc will show a module in its entirety.
97 perldoc -m POE::Loop::Select
99 perldoc -m POE::Loop::Gtk
100 ...
101
103 These functions initialize and finalize an event loop, run the loop to
104 process events, and halt it.
105 loop_initialize
107 Initialize the event loop. Graphical toolkits especially need some
108 sort of init() call or sequence to set up. For example,
109 POE::Loop::Gtk implements loop_initialize() like this.
110 sub loop_initialize {
112 Gtk->init;
113 }
114 POE::Loop::Select does a little more work.
116 sub loop_initialize {
118 @loop_vectors = ( '', '', '' );
119 vec($loop_vectors[MODE_RD], 0, 1) = 0;
120 vec($loop_vectors[MODE_WR], 0, 1) = 0;
121 vec($loop_vectors[MODE_EX], 0, 1) = 0;
122 }
123 loop_finalize
125 Finalize the event loop. Most event loops do not require anything
126 here since they have already stopped by the time loop_finalize() is
127 called. However, this is a good place to check that a bridge has not
128 leaked memory or data. This example comes from POE::Loop::Event.
129 sub loop_finalize {
131 foreach my $fd (0..$#fileno_watcher) {
132 next unless defined $fileno_watcher[$fd];
133 foreach my $mode (MODE_RD, MODE_WR, MODE_EX) {
134 warn "Fileno $fd / mode $mode has a watcher at loop_finalize"
135 if defined $fileno_watcher[$fd]->[$mode];
136 }
137 }
138 }
139 loop_do_timeslice
141 Wait for time to pass or new events to occur, and dispatch events
142 which are due. If the underlying event loop does these things, then
143 loop_do_timeslice() either provide- minimal glue for them or does
144 nothing.
145 For example, the loop_do_timeslice() function for the Select bridge
147 sets up and calls select(). If any files or other resources become
148 active, it enqueues events for them. Finally, it triggers dispatch
149 for any events are due.
150 On the other hand, the Gtk event loop handles all this, so
152 loop_do_timeslice() is empty for the Gtk bridge.
153 A sample loop_do_timeslice() is not presented here because it would
155 either be quite large or empty. See the bridges for Poll and Select
156 for large ones. The Event, Gtk, and Tk bridges are good examples of
157 empty ones.
158 loop_run
160 Run an event loop until POE has no more sessions to handle events.
161 This function tends to be quite small. For example, the Poll bridge
162 uses:
163 sub loop_run {
165 my $self = shift;
166 while ($self->_data_ses_count()) {
167 $self->loop_do_timeslice();
168 }
169 }
170 This function is even more trivial when an event loop handles it.
172 This is from the Gtk bridge:
173 sub loop_run {
175 Gtk->main;
176 }
177 loop_halt
179 Halt an event loop, especially one which does not know about POE.
180 This tends to be an empty function for loops written in the bridges
181 themselves (Poll, Select) and a trivial function for ones that have
182 their own main loops.
183 For example, the loop_run() function in the Poll bridge exits when
185 sessions have run out, so its loop_halt() function is empty:
186 sub loop_halt {
188 # does nothing
189 }
190 Gtk, however, needs to be stopped because it does not know when POE
192 is done.
193 sub loop_halt {
195 Gtk->main_quit();
196 }
197
199 These functions enable and disable signal watchers.
200 loop_watch_signal SIGNAL_NAME
202 Watch for a given SIGNAL_NAME, most likely by registering a signal
203 handler. Signal names are the ones included in %SIG. That is, they
204 are the UNIX signal names with the leading "SIG" removed.
205 Most event loops do not have native signal watchers, so it is up to
207 their bridges to register %SIG handlers. Some bridges, such as
208 POE::Loop::Event, register callbacks for various signals.
209 There are three types of signal handlers:
211 CHLD/CLD handlers, when managed by the bridges themselves, poll for
213 exited children. POE::Kernel does most of this, but loop_watch_sig‐
214 nal() still needs to start the process.
215 PIPE handlers. The PIPE signal event must be sent to the session
217 that is active when the signal occurred.
218 Everything else. Signal events for everything else are sent to
220 POE::Kernel, where they are distributed to every session.
221 The loop_watch_signal() function tends to be very long, so an example
223 is not presented here. The Event and Select bridges have good exam‐
224 ples, though.
225 loop_ignore_signal SIGNAL_NAME
227 Stop watching SIGNAL_NAME. This usually resets the %SIG entry for
228 SIGNAL_NAME to DEFAULT. In the Event bridge, however, it stops and
229 removes a watcher for the signal.
230 The Select bridge:
232 sub loop_ignore_signal {
234 my ($self, $signal) = @_;
235 $SIG{$signal} = "DEFAULT";
236 }
237 The Event bridge:
239 sub loop_ignore_signal {
241 my ($self, $signal) = @_;
242 if (defined $signal_watcher{$signal}) {
243 $signal_watcher{$signal}->stop();
244 delete $signal_watcher{$signal};
245 }
246 }
247 loop_attach_uidestroy WINDOW
249 Send a UIDESTROY signal when WINDOW is closed. The UIDESTROY signal
250 is used to shut down a POE program when its user interface is
251 destroyed.
252 This function is only meaningful in bridges that interface with
254 graphical toolkits. All other bridges leave loop_attach_uidestroy()
255 empty. See POE::Loop::Gtk and POE::Loop::Tk for examples.
256
258 These functions enable and disable a time watcher or alarm in the sub‐
259 strate. POE only requires one, which is reused or re-created as neces‐
260 sary.
261 Most event loops trigger callbacks when time has passed. Bridges for
263 this kind of loop will need to register and unregister a callback as
264 necessary. The callback, in turn, will dispatch due events and do some
265 other maintenance.
266 The bridge time functions accept NEXT_EVENT_TIME in the form of a UNIX
268 epoch time. Event times may contain fractional seconds. Time func‐
269 tions may be required to translate times from the UNIX epoch into what‐
270 ever representation an underlying event loop requires.
271 loop_resume_time_watcher NEXT_EVENT_TIME
273 Resume an already active time watcher. Used with
274 loop_pause_time_watcher() to provide lightweight timer toggling.
275 NEXT_EVENT_TIME is the UNIX epoch time of the next event in the
276 queue. This function is used by bridges that set time watchers in
277 other event loop libraries. For example, Gtk uses this:
278 sub loop_resume_time_watcher {
280 my ($self, $next_time) = @_;
281 $next_time -= time();
282 $next_time *= 1000;
283 $next_time = 0 if $next_time < 0;
284 $_watcher_timer = Gtk->timeout_add( $next_time,
285 \&_loop_event_callback
286 );
287 }
288 It is often empty in bridges that implement their own event loops.
290 loop_reset_time_watcher NEXT_EVENT_TIME
292 Reset a time watcher, often by stopping or destroying an existing one
293 and creating a new one in its place. This function has the same
294 semantics as (and is often implemented in terms of)
295 loop_resume_time_watcher(). It is usually more expensive than that
296 function, however. Again, from Gtk:
297 sub loop_reset_time_watcher {
299 my ($self, $next_time) = @_;
300 Gtk->timeout_remove($_watcher_timer);
301 undef $_watcher_timer;
302 $self->loop_resume_time_watcher($next_time);
303 }
304 loop_pause_time_watcher
306 Pause a time watcher. This should be done without destroying the
307 timer, if the underlying event loop supports that.
308 POE::Loop::Event supports pausing a timer:
310 sub loop_pause_time_watcher {
312 $_watcher_timer->stop();
313 }
314
316 These functions enable and disable file activity watchers. The pause
317 and resume functions are lightweight versions of ignore and watch.
318 They are used to quickly toggle the state of a file activity watcher
319 without incurring the overhead of destroying and creating them
320 entirely.
321 All the functions take the same two parameters: a file HANDLE and a
323 file access MODE.
324 Modes may be MODE_RD, MODE_WR, or MODE_EX. These constants are defined
326 by POE::Kernel and correspond to read, write, or exceptions.
327 POE calls MODE_EX "expedited" because it often signals that a file is
329 ready for out-of-band information. Not all event loops handle MODE_EX.
330 For example, Tk:
331 sub loop_watch_filehandle {
333 my ($self, $handle, $mode) = @_;
334 my $fileno = fileno($handle);
335 # The Tk documentation implies by omission that expedited
337 # filehandles aren't, uh, handled. This is part 1 of 2.
338 confess "Tk does not support expedited filehandles"
339 if $mode == MODE_EX;
340 ...
341 }
342 loop_watch_filehandle HANDLE, MODE
344 Watch a file HANDLE for activity in a given MODE. Registers the HAN‐
345 DLE (or, more often its file descriptor via fileno()) in the given
346 MODE with the underlying event loop.
347 POE::Loop::Select sets a vec() bit so the next select() call will
349 know about the handle. It also tracks which file descriptors it has
350 active.
351 sub loop_watch_filehandle {
353 my ($self, $handle, $mode) = @_;
354 my $fileno = fileno($handle);
355 vec($loop_vectors[$mode], $fileno, 1) = 1;
356 $loop_filenos{$fileno} ⎪= (1<<$mode);
357 }
358 loop_ignore_filehandle HANDLE, MODE
360 Stop watching a file HANDLE in a given MODE. Stops (and possibly
361 destroys) an event watcher corresponding to the HANDLE and MODE.
362 POE::Loop::IO_Poll manages the descriptor/mode bits out of its
364 loop_ignore_filehandle() function. It also performs some cleanup if
365 a descriptors has been totally ignored.
366 sub loop_ignore_filehandle {
368 my ($self, $handle, $mode) = @_;
369 my $fileno = fileno($handle);
370 my $type = mode_to_poll($mode);
372 my $current = $poll_fd_masks{$fileno} ⎪⎪ 0;
373 my $new = $current & ~$type;
374 if ($new) {
376 $poll_fd_masks{$fileno} = $new;
377 }
378 else {
379 delete $poll_fd_masks{$fileno};
380 }
381 }
382 loop_pause_filehandle HANDLE, MODE
384 This is a lightweight form of loop_ignore_filehandle(). It is used
385 along with loop_resume_filehandle() to temporarily toggle a watcher's
386 state for a file HANDLE in a particular mode.
387 Some event loops, such as Event.pm, support their file watchers being
389 disabled and re-enabled without the need to destroy and re-create
390 entire objects.
391 sub loop_pause_filehandle {
393 my ($self, $handle, $mode) = @_;
394 my $fileno = fileno($handle);
395 $fileno_watcher[$fileno]->[$mode]->stop();
396 }
397 By comparison, the loop_ignore_filehandle() function for Event.pm
399 involves canceling and destroying a watcher object. This can be
400 quite expensive.
401 sub loop_ignore_filehandle {
403 my ($self, $handle, $mode) = @_;
404 my $fileno = fileno($handle);
405 # Don't bother removing a select if none was registered.
407 if (defined $fileno_watcher[$fileno]->[$mode]) {
408 $fileno_watcher[$fileno]->[$mode]->cancel();
409 undef $fileno_watcher[$fileno]->[$mode];
410 }
411 }
412 loop_resume_filehandle HANDLE, MODE
414 This is a lightweight form of loop_watch_filehandle(). It is used
415 along with loop_pause_filehandle() to temporarily toggle a a
416 watcher's state for a file HANDLE in a particular mode.
417
419 The first time POE::Kernel is used, it examines the modules currently
420 loaded in memory and tries to load an appropriate POE::Loop subclass
421 based on what it discovers.
422 Firstly, if a POE::Loop class is manually loaded before POE::Kernel,
424 then that will be used. End of story.
425 If one isn't, POE::Kernel iterates through %INC to discover which mod‐
427 ules are already loaded. For each of them, it tries to load a simi‐
428 larly-named POE::XS::Loop class, then it tries a corresponding
429 POE::Loop class. For example, if IO::Poll is loaded, POE::Kernel tries
430 use POE::XS::Loop::IO_Poll;
432 use POE::Loop::IO_Poll;
433 POE::Loop::Select is the fallback event loop. It's loaded if none of
435 the currently loaded modules has its own POE::Loop class.
436 It can't be repeated often enough that event loops must be loaded
438 before POE::Kernel. Otherwise POE::Kernel will not detect the event
439 loop you want to use, and the wrong POE::Loop class will be loaded.
440
442 POE, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
443 POE::Loop::Select, POE::Loop::Tk.
444
446 Signal handlers are often repeated between bridges:
447 http://rt.cpan.org/NoAuth/Bug.html?id=1632
448
450 Please see POE for more information about authors, contributors, and
451 POE's licensing.
452perl v5.8.8 2006-09-01 POE::Loop(3)