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