| Current File : //usr/local/share/man/man3/POE::Loop.3pm |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Loop 3"
.TH POE::Loop 3 "2022-03-23" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Loop \- documentation for POE's event loop bridge interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& $kernel\->loop_initialize();
\& $kernel\->loop_finalize();
\& $kernel\->loop_do_timeslice();
\& $kernel\->loop_run();
\& $kernel\->loop_halt();
\&
\& $kernel\->loop_watch_signal($signal_name);
\& $kernel\->loop_ignore_signal($signal_name);
\& $kernel\->loop_attach_uidestroy($gui_window);
\&
\& $kernel\->loop_resume_time_watcher($next_time);
\& $kernel\->loop_reset_time_watcher($next_time);
\& $kernel\->loop_pause_time_watcher();
\&
\& $kernel\->loop_watch_filehandle($handle, $mode);
\& $kernel\->loop_ignore_filehandle($handle, $mode);
\& $kernel\->loop_pause_filehandle($handle, $mode);
\& $kernel\->loop_resume_filehandle($handle, $mode);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Loop is a virtual base class that defines a standard event loop
interface. POE::Loop subclasses mix into POE::Kernel and implement
the features needed to manage underlying event loops in a consistent
fashion. This documentation covers the interface, which is shared by
all subclasses.
.PP
As POE::Kernel loads, it searches through \f(CW%INC\fR for event loop modules.
POE::Kernel loads the most appropriate POE::Loop subclass for the
event loop it finds. The subclass slots its methods into POE::Kernel,
completing the class at load time. \s-1POE\s0 and POE::Kernel provide ways
to state the desired event loop in case the auto-detection makes a
mistake or the developer prefers to be explicit. See
\&\*(L"Using \s-1POE\s0 with Other Event Loops\*(R" in POE::Kernel for instructions on
how to actually use \s-1POE\s0 with other event loops, event loop naming
conventions, and other details.
.PP
POE::Loop subclasses exist for many of the event loops Perl supports:
\&\fBselect()\fR, IO::Poll, WxWindows, \s-1EV,\s0 Glib, Event, and so on. See \s-1CPAN\s0
for a full list.
.SH "GENERAL NOTES"
.IX Header "GENERAL NOTES"
As previously noted, POE::Loop subclasses provide additional methods
to POE::Kernel and are not proper objects in themselves.
.PP
Each POE::Loop subclass first defines its own namespace and version
within it. This way \s-1CPAN\s0 and other things can track its version.
They then switch to the POE::Kernel package to define their additional
methods.
.PP
POE::Loop is designed as a mix-in class because Perl imposed a
performance penalty for method inheritance at the time the class was
designed. This could be changed in the future, but it will require
cascaded changes in several other classes.
.PP
Here is a skeleton of a POE::Loop subclass:
.PP
.Vb 1
\& use strict;
\&
\& # YourToolkit bridge for POE::Kernel;
\&
\& package POE::Loop::YourToolkit;
\&
\& use vars qw($VERSION);
\& $VERSION = \*(Aq1.000\*(Aq; # NOTE \- Should be #.### (three decimal places)
\&
\& package POE::Kernel;
\&
\& # Define private lexical data here.
\& # Implement the POE::Loop interface here.
\&
\& 1;
\&
\& _\|_END_\|_
\&
\& =head1 NAME
\&
\& ... documentation goes here ...
\&
\& =cut
.Ve
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
POE::Loop's public interface is divided into four parts:
administrative methods, signal handler methods, time management
methods, and filehandle watcher methods. Each group and its members
will be described in detail shortly.
.PP
POE::Loop subclasses use lexical variables to keep track of things.
Exact implementation is left up to the subclass' author.
POE::Loop::Select keeps its bit vectors for \fBselect()\fR calls in
class-scoped (static) lexical variables. POE::Loop::Gtk tracks a
single time watcher and multiple file watchers there.
.PP
Bridges often employ private methods as callbacks from their event
loops. The Event, Gtk, and Tk bridges do this. Private callback
names should begin with \*(L"_loop_\*(R" to avoid colliding with other
methods.
.PP
Developers should look at existing bridges to get a feel for things.
The \f(CW\*(C`\-m\*(C'\fR flag for perldoc will show a module in its entirety.
.PP
.Vb 3
\& perldoc \-m POE::Loop::Select
\& perldoc \-m POE::Loop::Gtk
\& ...
.Ve
.SS "Administrative Methods"
.IX Subsection "Administrative Methods"
These methods initialize and finalize an event loop, run the loop to
process events, and halt it.
.PP
\fIloop_initialize\fR
.IX Subsection "loop_initialize"
.PP
Initialize the event loop. Graphical toolkits especially need some
sort of \fBinit()\fR call or sequence to set up. For example, Tk requires a
widget to be created before any events will be processed, and the
program's user interface will be considered destroyed if that widget
is closed.
.PP
.Vb 2
\& sub loop_initialize {
\& my $self = shift;
\&
\& $poe_main_window = Tk::MainWindow\->new();
\& die "could not create a main Tk window" unless defined $poe_main_window;
\& $self\->signal_ui_destroy($poe_main_window);
\& }
.Ve
.PP
POE::Loop::Select initializes its \fBselect()\fR bit vectors.
.PP
.Vb 6
\& sub loop_initialize {
\& @loop_vectors = ( \*(Aq\*(Aq, \*(Aq\*(Aq, \*(Aq\*(Aq );
\& vec($loop_vectors[MODE_RD], 0, 1) = 0;
\& vec($loop_vectors[MODE_WR], 0, 1) = 0;
\& vec($loop_vectors[MODE_EX], 0, 1) = 0;
\& }
.Ve
.PP
\fIloop_finalize\fR
.IX Subsection "loop_finalize"
.PP
Finalize the event loop. Most event loops do not require anything
here since they have already stopped by the time \fBloop_finalize()\fR is
called. However, this is a good place to check that a bridge has not
leaked memory or data. This example comes from POE::Loop::Event.
.PP
.Vb 2
\& sub loop_finalize {
\& my $self = shift;
\&
\& foreach my $fd (0..$#fileno_watcher) {
\& next unless defined $fileno_watcher[$fd];
\& foreach my $mode (MODE_RD, MODE_WR, MODE_EX) {
\& POE::Kernel::_warn(
\& "Mode $mode watcher for fileno $fd is defined during loop finalize"
\& ) if defined $fileno_watcher[$fd]\->[$mode];
\& }
\& }
\&
\& $self\->loop_ignore_all_signals();
\& }
.Ve
.PP
\fIloop_do_timeslice\fR
.IX Subsection "loop_do_timeslice"
.PP
Wait for time to pass or new events to occur, and dispatch any events
that become due. If the underlying event loop does this through
callbacks, then \fBloop_do_timeslice()\fR will either provide minimal glue
or do nothing.
.PP
For example, \fBloop_do_timeslice()\fR for POE::Loop::Select sets up and
calls \fBselect()\fR. If any files or other resources become active, it
enqueues events for them. Finally, it triggers dispatch for any
events are due.
.PP
On the other hand, the Gtk event loop handles all this, so
\&\fBloop_do_timeslice()\fR is empty for the Gtk bridge.
.PP
A sample \fBloop_do_timeslice()\fR implementation is not presented here
because it would either be quite large or empty. See each
POE::Loop::IO_Poll or Select for large ones. Event and Gtk are empty.
.PP
The bridges for Poll and Select for large ones. The ones for Event
and Gtk are empty, and Tk's (in POE::Loop::TkCommon) is rather small.
.PP
\fIloop_run\fR
.IX Subsection "loop_run"
.PP
Run an event loop until \s-1POE\s0 has no more sessions to handle events.
This method tends to be quite small, and it is often implemented in
terms of \fBloop_do_timeslice()\fR. For example, POE::Loop::IO_Poll
implements it:
.PP
.Vb 6
\& sub loop_run {
\& my $self = shift;
\& while ($self\->_data_ses_count()) {
\& $self\->loop_do_timeslice();
\& }
\& }
.Ve
.PP
This method is even more trivial when an event loop handles it. This
is from the Gtk bridge:
.PP
.Vb 6
\& sub loop_run {
\& unless (defined $_watcher_timer) {
\& $_watcher_timer = Gtk\->idle_add(\e&_loop_resume_timer);
\& }
\& Gtk\->main;
\& }
.Ve
.PP
\fIloop_halt\fR
.IX Subsection "loop_halt"
.PP
\&\fBloop_halt()\fR does what it says: It halts \s-1POE\s0's underlying event loop.
It tends to be either trivial for external event loops or empty for
ones that are implemented in the bridge itself (IO_Poll, Select).
.PP
For example, the \fBloop_run()\fR method in the Poll bridge exits when
sessions have run out, so its \fBloop_halt()\fR method is empty:
.PP
.Vb 3
\& sub loop_halt {
\& # does nothing
\& }
.Ve
.PP
Gtk, however, needs to be stopped because it does not know when \s-1POE\s0 is
done.
.PP
.Vb 3
\& sub loop_halt {
\& Gtk\->main_quit();
\& }
.Ve
.SS "Signal Management Methods"
.IX Subsection "Signal Management Methods"
These methods enable and disable signal watchers. They are used by
POE::Resource::Signals to manage an event loop's signal watchers.
.PP
Most event loops use Perl's \f(CW%SIG\fR to watch for signals. This is so
common that POE::Loop::PerlSignals implements the interface on behalf
of other subclasses.
.PP
\fIloop_watch_signal \s-1SIGNAL_NAME\s0\fR
.IX Subsection "loop_watch_signal SIGNAL_NAME"
.PP
Watch for a given \s-1SIGNAL_NAME.\s0 \s-1SIGNAL_NAME\s0 is the version found in
\&\f(CW%SIG\fR, which tends to be the operating signal's name with the leading
\&\*(L"\s-1SIG\*(R"\s0 removed.
.PP
POE::Loop::PerlSignals' implementation adds callbacks to \f(CW%SIG\fR except
for \s-1CHLD/CLD,\s0 which begins a \fBwaitpid()\fR polling loop instead.
.PP
As of this writing, all of the POE::Loop subclasses register their
signal handlers through POE::Loop::PerlSignals.
.PP
There are three types of signal handlers:
.PP
\&\s-1CHLD/CLD\s0 handlers, when managed by the bridges themselves, poll for
exited children. POE::Kernel does most of this, but
\&\fBloop_watch_signal()\fR still needs to start the process.
.PP
\&\s-1PIPE\s0 handlers. The \s-1PIPE\s0 signal event must be sent to the session that
is active when the signal occurred.
.PP
Everything else. Signal events for everything else are sent to
POE::Kernel, where they are distributed to every session.
.PP
The \fBloop_watch_signal()\fR methods tends to be very long, so an example
is not presented here. The Event and Select bridges have good
examples, though.
.PP
\fIloop_ignore_signal \s-1SIGNAL_NAME\s0\fR
.IX Subsection "loop_ignore_signal SIGNAL_NAME"
.PP
Stop watching \s-1SIGNAL_NAME.\s0 POE::Loop::PerlSignals does this by
resetting the \f(CW%SIG\fR for the \s-1SIGNAL_NAME\s0 to a sane value.
.PP
\&\f(CW$SIG\fR{\s-1CHLD\s0} is left alone so as to avoid interfering with \fBsystem()\fR and
other things.
.PP
\&\s-1SIGPIPE\s0 is generally harmless since \s-1POE\s0 generates events for this
condition. Therefore \f(CW$SIG\fR{\s-1PIPE\s0} is set to \*(L"\s-1IGNORE\*(R"\s0 when it's not
being handled.
.PP
All other signal handlers default to \*(L"\s-1DEFAULT\*(R"\s0 when not in use.
.PP
\fIloop_attach_uidestroy \s-1WIDGET\s0\fR
.IX Subsection "loop_attach_uidestroy WIDGET"
.PP
\&\s-1POE,\s0 when used with a graphical toolkit, should shut down when the
user interface is closed. \fBloop_attach_uidestroy()\fR is used to shut
down \s-1POE\s0 when a particular \s-1WIDGET\s0 is destroyed.
.PP
The shutdown is done by firing a \s-1UIDESTROY\s0 signal when the \s-1WIDGET\s0's
closure or destruction callback is invoked. \s-1UIDESTROY\s0 guarantees the
program will shut down by virtue of being terminal and non-maskable.
.PP
\&\fBloop_attach_uidestroy()\fR is only meaningful in POE::Loop subclasses
that tie into user interfaces. All other subclasses leave the method
empty.
.PP
Here's Gtk's:
.PP
.Vb 10
\& sub loop_attach_uidestroy {
\& my ($self, $window) = @_;
\& $window\->signal_connect(
\& delete_event => sub {
\& if ($self\->_data_ses_count()) {
\& $self\->_dispatch_event(
\& $self, $self,
\& EN_SIGNAL, ET_SIGNAL, [ \*(AqUIDESTROY\*(Aq ],
\& _\|_FILE_\|_, _\|_LINE_\|_, undef, monotime(), \-_\|_LINE_\|_
\& );
\& }
\& return 0;
\& }
\& );
\& }
.Ve
.SS "Alarm and Time Management Methods"
.IX Subsection "Alarm and Time Management Methods"
These methods enable and disable a time watcher or alarm in the
underlying event loop. \s-1POE\s0 only requires one, which is reused or
re-created as necessary.
.PP
Most event loops trigger callbacks when time has passed. It is the
bridge's responsibility to register and unregister a callback as
needed. When invoked, the callback should dispatch events that have
become due and possibly set up a new callback for the next event to be
dispatched.
.PP
The time management methods may accept \s-1NEXT_EVENT_TIME.\s0 This is the
time the next event will become due, in \s-1UNIX\s0 epoch time.
\&\s-1NEXT_EVENT_TIME\s0 is a real number and may have sub-second accuracy. It
is the bridge's responsibility to convert this value into something
the underlying event loop requires.
.PP
\fIloop_resume_time_watcher \s-1NEXT_EVENT_TIME\s0\fR
.IX Subsection "loop_resume_time_watcher NEXT_EVENT_TIME"
.PP
Resume an already active time watcher. It is used with
\&\fBloop_pause_time_watcher()\fR to provide less expensive timer toggling for
frequent use cases. As mentioned above, \s-1NEXT_EVENT_TIME\s0 is in \s-1UNIX\s0
epoch time and may have sub-second accuracy.
.PP
\&\fBloop_resume_time_watcher()\fR is used by bridges that set them watchers
in the underlying event loop. For example, POE::Loop::Gtk implements
it this way:
.PP
.Vb 9
\& sub loop_resume_time_watcher {
\& my ($self, $next_time) = @_;
\& $next_time \-= time();
\& $next_time *= 1000;
\& $next_time = 0 if $next_time < 0;
\& $_watcher_timer = Gtk\->timeout_add(
\& $next_time, \e&_loop_event_callback
\& );
\& }
.Ve
.PP
This method is usually empty in bridges that implement their own event
loops.
.PP
\fIloop_reset_time_watcher \s-1NEXT_EVENT_TIME\s0\fR
.IX Subsection "loop_reset_time_watcher NEXT_EVENT_TIME"
.PP
Reset a time watcher, often by stopping or destroying an existing one
and creating a new one in its place. It is often a wrapper for
\&\fBloop_resume_time_watcher()\fR that first destroys an existing watcher.
For example, POE::Loop::Gkt's implementation:
.PP
.Vb 6
\& sub loop_reset_time_watcher {
\& my ($self, $next_time) = @_;
\& Gtk\->timeout_remove($_watcher_timer);
\& undef $_watcher_timer;
\& $self\->loop_resume_time_watcher($next_time);
\& }
.Ve
.PP
\fIloop_pause_time_watcher\fR
.IX Subsection "loop_pause_time_watcher"
.PP
Pause a time watcher without destroying it, if the underlying event
loop supports such a thing. POE::Loop::Event does support it:
.PP
.Vb 4
\& sub loop_pause_time_watcher {
\& $_watcher_timer or return;
\& $_watcher_timer\->stop();
\& }
.Ve
.SS "File Activity Management Methods"
.IX Subsection "File Activity Management Methods"
These methods enable and disable file activity watchers. There are
four methods: \fBloop_watch_filehandle()\fR, \fBloop_ignore_filehandle()\fR,
\&\fBloop_pause_filehandle()\fR, and \fBloop_resume_filehandle()\fR. The \*(L"pause\*(R"
and \*(L"resume\*(R" methods are lightweight versions of \*(L"ignore\*(R" and \*(L"watch\*(R",
respectively.
.PP
All the methods take the same two parameters: a file \s-1HANDLE\s0 and a file
access \s-1MODE.\s0 Modes may be \s-1MODE_RD, MODE_WR,\s0 or \s-1MODE_EX.\s0 These
constants are defined by POE::Kernel and correspond to the semantics
of POE::Kernel's \fBselect_read()\fR, \fBselect_write()\fR, and \fBselect_expedite()\fR
methods.
.PP
\&\s-1POE\s0 calls \s-1MODE_EX\s0 \*(L"expedited\*(R" because it often signals that a file is
ready for out-of-band information. Not all event loops handle
\&\s-1MODE_EX.\s0 For example, Tk:
.PP
.Vb 3
\& sub loop_watch_filehandle {
\& my ($self, $handle, $mode) = @_;
\& my $fileno = fileno($handle);
\&
\& my $tk_mode;
\& if ($mode == MODE_RD) {
\& $tk_mode = \*(Aqreadable\*(Aq;
\& }
\& elsif ($mode == MODE_WR) {
\& $tk_mode = \*(Aqwritable\*(Aq;
\& }
\& else {
\& # The Tk documentation implies by omission that expedited
\& # filehandles aren\*(Aqt, uh, handled. This is part 1 of 2.
\& confess "Tk does not support expedited filehandles";
\& }
\&
\& # ... rest omitted ....
\& }
.Ve
.PP
\fIloop_watch_filehandle \s-1FILE_HANDLE, IO_MODE\s0\fR
.IX Subsection "loop_watch_filehandle FILE_HANDLE, IO_MODE"
.PP
Watch a \s-1FILE_HANDLE\s0 for activity in a given \s-1IO_MODE.\s0 Depending on the
underlying event loop, a watcher or callback will be registered for
the \s-1FILE_HANDLE.\s0 Activity in the specified \s-1IO_MODE\s0 (read, write, or
out of band) will trigger emission of the proper event in application
space.
.PP
POE::Loop::Select sets the \fBfileno()\fR's bit in the proper \fBselect()\fR bit
vector. It also keeps track of which file descriptors are active.
.PP
.Vb 6
\& sub loop_watch_filehandle {
\& my ($self, $handle, $mode) = @_;
\& my $fileno = fileno($handle);
\& vec($loop_vectors[$mode], $fileno, 1) = 1;
\& $loop_filenos{$fileno} |= (1<<$mode);
\& }
.Ve
.PP
\fIloop_ignore_filehandle \s-1FILE_HANDLE, IO_MODE\s0\fR
.IX Subsection "loop_ignore_filehandle FILE_HANDLE, IO_MODE"
.PP
Stop watching the \s-1FILE_HANDLE\s0 in a given \s-1IO_MODE.\s0 Stops (and possibly
destroys) an event watcher corresponding to the \s-1FILE_HANDLE\s0 and
\&\s-1IO_MODE.\s0
.PP
POE::Loop::IO_Poll's \fBloop_ignore_filehandle()\fR manages descriptor/mode
bits for its \fB_poll()\fR method here. It also performs some cleanup if a
descriptor is no longer being watched after this ignore call.
.PP
.Vb 3
\& sub loop_ignore_filehandle {
\& my ($self, $handle, $mode) = @_;
\& my $fileno = fileno($handle);
\&
\& my $type = mode_to_poll($mode);
\& my $current = $poll_fd_masks{$fileno} || 0;
\& my $new = $current & ~$type;
\&
\& if (TRACE_FILES) {
\& POE::Kernel::_warn(
\& sprintf(
\& "<fh> Ignore $fileno: " .
\& ": Current mask: 0x%02X \- removing 0x%02X = 0x%02X\en",
\& $current, $type, $new
\& )
\& );
\& }
\&
\& if ($new) {
\& $poll_fd_masks{$fileno} = $new;
\& }
\& else {
\& delete $poll_fd_masks{$fileno};
\& }
\& }
.Ve
.PP
\fIloop_pause_filehandle \s-1FILE_HANDLE, IO_MODE\s0\fR
.IX Subsection "loop_pause_filehandle FILE_HANDLE, IO_MODE"
.PP
This is a lightweight form of \fBloop_ignore_filehandle()\fR. It is used
along with \fBloop_resume_filehandle()\fR to temporarily toggle a watcher's
state for a \s-1FILE_HANDLE\s0 in a particular \s-1IO_MODE.\s0
.PP
Some event loops, such as Event.pm, support their file watchers being
disabled and re-enabled without the need to destroy and re-create
the watcher objects.
.PP
.Vb 5
\& sub loop_pause_filehandle {
\& my ($self, $handle, $mode) = @_;
\& my $fileno = fileno($handle);
\& $fileno_watcher[$fileno]\->[$mode]\->stop();
\& }
.Ve
.PP
By comparison, Event's \fBloop_ignore_filehandle()\fR method cancels and
destroys the watcher object.
.PP
.Vb 8
\& sub loop_ignore_filehandle {
\& my ($self, $handle, $mode) = @_;
\& my $fileno = fileno($handle);
\& if (defined $fileno_watcher[$fileno]\->[$mode]) {
\& $fileno_watcher[$fileno]\->[$mode]\->cancel();
\& undef $fileno_watcher[$fileno]\->[$mode];
\& }
\& }
.Ve
.PP
Ignoring and re-creating watchers is relatively expensive, so
POE::Kernel's \fBselect_pause_read()\fR and \fBselect_resume_read()\fR methods
(and the corresponding ones for write and expedite) use the faster
versions.
.PP
\fIloop_resume_filehandle \s-1FILE_HANDLE, IO_MODE\s0\fR
.IX Subsection "loop_resume_filehandle FILE_HANDLE, IO_MODE"
.PP
This is a lightweight form of \fBloop_watch_filehandle()\fR. It is used
along with \fBloop_pause_filehandle()\fR to temporarily toggle a watcher's
state for a \s-1FILE_HANDLE\s0 in a particular \s-1IO_MODE.\s0
.SH "HOW POE FINDS EVENT LOOP BRIDGES"
.IX Header "HOW POE FINDS EVENT LOOP BRIDGES"
This is a rehash of \*(L"Using \s-1POE\s0 with Other Event Loops\*(R" in POE::Kernel.
.PP
Firstly, if a POE::Loop subclass is manually loaded before
POE::Kernel, then that will be used. End of story.
.PP
If one isn't, POE::Kernel searches for an external event loop module
in \f(CW%INC\fR. For each module in \f(CW%INC\fR, corresponding POE::XS::Loop and
POE::Loop subclasses are tried.
.PP
For example, if IO::Poll is loaded, POE::Kernel tries
.PP
.Vb 2
\& use POE::XS::Loop::IO_Poll;
\& use POE::Loop::IO_Poll;
.Ve
.PP
This is relatively expensive, but it ensures that POE::Kernel can find
new POE::Loop subclasses without defining them in a central registry.
.PP
POE::Loop::Select is the fallback event loop. It's loaded if no other
event loop can be found in \f(CW%INC\fR.
.PP
It can't be repeated often enough that event loops must be loaded
before POE::Kernel. Otherwise they will not be present in \f(CW%INC\fR, and
POE::Kernel will not detect them.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1POE\s0, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IO_Poll,
POE::Loop::Select, POE::Loop::Tk.
.PP
POE::Test::Loops is \s-1POE\s0's event loop tests released as a separate,
reusable distribution. POE::Loop authors are encouraged to use the
tests for their own distributions.
.SH "BUGS"
.IX Header "BUGS"
None known.
.SH "AUTHORS & LICENSING"
.IX Header "AUTHORS & LICENSING"
Please see \s-1POE\s0 for more information about authors, contributors,
and \s-1POE\s0's licensing.