view release on metacpan or  search on metacpan

lib/POE/Loop.pm  view on Meta::CPAN

=head1 NAME

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

=head1 SYNOPSIS

  $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);

=head1 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.

As POE::Kernel loads, it searches through %INC 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.  POE 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<POE::Kernel/"Using POE with Other Event Loops"> for instructions on
how to actually use POE with other event loops, event loop naming
conventions, and other details.

POE::Loop subclasses exist for many of the event loops Perl supports:
select(), IO::Poll, WxWindows, EV, Glib, Event, and so on.  See CPAN
for a full list.

=head1 GENERAL NOTES

As previously noted, POE::Loop subclasses provide additional methods
to POE::Kernel and are not proper objects in themselves.

Each POE::Loop subclass first defines its own namespace and version
within it.  This way CPAN and other things can track its version.
They then switch to the POE::Kernel package to define their additional
methods.

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.

Here is a skeleton of a POE::Loop subclass:

  use strict;

  # YourToolkit bridge for POE::Kernel;

  package POE::Loop::YourToolkit;

  use vars qw($VERSION);
  $VERSION = '1.000'; # 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

=head1 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.

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 select() calls in
class-scoped (static) lexical variables.  POE::Loop::Gtk tracks a
single time watcher and multiple file watchers there.

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 "_loop_" to avoid colliding with other
methods.

Developers should look at existing bridges to get a feel for things.
The C<-m> flag for perldoc will show a module in its entirety.

  perldoc -m POE::Loop::Select
  perldoc -m POE::Loop::Gtk
  ...

=head2 Administrative Methods

These methods initialize and finalize an event loop, run the loop to
process events, and halt it.

=head3 loop_initialize

Initialize the event loop.  Graphical toolkits especially need some