Permalink
Browse files

Several doc changes to fix issues reported by garu in irc.perl.org

#poe.  Thanks, garu!
  • Loading branch information...
1 parent b97cd07 commit 9b1c68908d41c97733acbaf3658fc6510813e5af @rcaputo committed Jan 6, 2010
Showing with 79 additions and 34 deletions.
  1. +3 −4 lib/POE.pm
  2. +53 −11 lib/POE/Kernel.pm
  3. +23 −19 lib/POE/Session.pm
View
@@ -365,10 +365,9 @@ see the GETTING HELP section if you run into a problem.
POE is expected to work on most forms of UNIX, including FreeBSD,
MacOS X, Linux, Solaris. Maybe even AIX and QNX, but we're not sure.
-POE has also been tested on Windows XP, using the latest version of
-ActiveState Perl and Cygwin Perl. Support for the Neopolitan Perls
-(Vanilla, Strawberry and Chocolate) is still early, but there should
-be no major show stoppers.
+POE is also tested on Windows XP, using the latest version of
+ActiveState, Strawberry and Cygwin Perl. POE is fully supported with
+Strawberry Perl, as it's included in the Strawberry distribution.
OS/2 and MacOS 9 have been reported to work in the past, but nobody
seems to be testing there anymore. Reports and patches are still
View
@@ -2949,27 +2949,33 @@ code references that will generate POE events when called.
Applications can pass these code references to event loops for use as
callbacks.
-These are the four loops included in POE's distribution:
+POE's distribution includes two event loop interfaces. CPAN holds
+several more:
=head3 POE::Loop::Select
By default POE uses its select() based loop to drive its event system.
This is perhaps the least efficient loop, but it is also the most
portable. POE optimizes for correctness above all.
-=head3 POE::Loop::Event
+=head3 POE::Loop::IO_Poll
+
+The L<IO::Poll|IO::Poll> event loop provides an alternative that
+theoretically scales better than select().
+
+=head3 POE::Loop::Event (separate distribution)
This event loop provides interoperability with other modules that use
L<Event>. It may also provide a performance boost because L<Event> is
written in a compiled language. Unfortunately, this makes L<Event>
less portable than Perl's built-in select().
-=head3 POE::Loop::Gtk
+=head3 POE::Loop::Gtk (separate distribution)
This event loop allows programs to work under the L<Gtk> graphical
toolkit.
-=head3 POE::Loop::Tk
+=head3 POE::Loop::Tk (separate distribution)
This event loop allows programs to work under the L<Tk> graphical
toolkit. Tk has some restrictions that require POE to behave oddly.
@@ -2983,10 +2989,50 @@ need it other than for dispatching events.
Creating and using a different MainWindow often has an undesired
outcome.
-=head3 POE::Loop::IO_Poll
+=head3 POE::Loop::EV (separate distribution)
-The L<IO::Poll|IO::Poll> event loop provides an alternative that
-theoretically scales better than select().
+L<POE::Loop::EV> allows POE-based programs to use the EV event library
+with little or no change.
+
+=head3 POE::Loop::Glib (separate distribution)
+
+L<POE::Loop::Glib> allows POE-based programs to use Glib with little
+or no change. It also supports embedding POE-based programs into
+applications that already use Glib. For example, we have heard that
+POE has successfully embedded into vim, irssi and xchat via this loop.
+
+=head3 POE::Loop::Kqueue (separate distribution)
+
+L<POE::Loop::Kqueue> allows POE-based programs to transparently use
+the BSD kqueue event library on operating systems that support it.
+
+=head3 POE::Loop::Prima (separate distribution)
+
+L<POE::Loop::Prima> allows POE-based programs to use Prima's event
+loop with little or no change. It allows POE libraries to be used
+within Prima applications.
+
+=head3 POE::Loop::Wx (separate distribution)
+
+L<POE::Loop::Wx> allows POE-based programs to use Wx's event loop with
+little or no change. It allows POE libraries to be used within Wx
+applications, such as Padre.
+
+=head3 POE::XS::Loop::EPoll (separate distribution)
+
+L<POE::Loop::EPoll> allows POE components to trnasparently use the
+EPoll event library on operating systems that support it.
+
+=head3 POE::XS::Loop::Poll (separate distribution)
+
+L<POE::XS::Loop::Poll> is a higher-performance C-based libpoll event
+loop. It replaces some of POE's hot Perl code with C for better
+performance.
+
+=head3 Other Event Loops (separate distributions)
+
+POE may be extended to handle other event loops. Developers are
+invited to work with us to support their favorite loops.
=head1 PUBLIC METHODS
@@ -5382,10 +5428,6 @@ names from clashing.
There is no mechanism to catch exceptions generated in another session.
-=item *
-
-Probably lots more.
-
=back
=head1 AUTHORS & COPYRIGHTS
View
@@ -824,12 +824,12 @@ Notice that the created POE::Session object has not been saved to a
variable. The new POE::Session object gives itself to POE::Kernel,
which then manages it and all the resources it uses.
-It's possible to keep references to new POE::Session objects, but it's
-not usually necessary. If an application is not careful about
-cleaning up these references you will create circular references,
-which will leak memory when POE::Kernel would normally destroy
-the POE::Session object. It is recommended that you keep
-the session's C</ID> instead.
+It's possible to keep references to new POE::Session objects, but it's
+not usually necessary. If an application is not careful about
+cleaning up these references you will create circular references,
+which will leak memory when POE::Kernel would normally destroy the
+POE::Session object. It is recommended that you keep the session's
+C</ID> instead.
=head2 POE::Session's Calling Convention
@@ -841,16 +841,17 @@ POE::Session's unconventional calling convention. For example:
...;
}
-Or the use of CL</$_[KERNEL]>, CL</$_[HEAP]> and CL</$_[ARG0]> inline, as is done
-in most examples.
+Or the use of C</$_[KERNEL]>, C</$_[HEAP]> and C</$_[ARG0]> inline,
+as is done in most examples.
What's going on here is rather basic. Perl passes parameters into
-subroutines or methods using the @_ array. C<KERNEL>, C<HEAP>, C<ARG0> and
-others are constants exported by POE::Session (which is included for
-free when a program uses POE).
+subroutines or methods using the @_ array. C<KERNEL>, C<HEAP>,
+C<ARG0> and others are constants exported by POE::Session (which is
+included for free when a program uses POE).
-So CL</$_[KERNEL]> is an event handler's KERNELth parameter. C<@_[HEAP,
-ARG0]> is a slice of @_ containing the HEAPth and ARG0th parameters.
+So C</$_[KERNEL]> is an event handler's KERNELth parameter.
+C<@_[HEAP, ARG0]> is a slice of @_ containing the HEAPth and ARG0th
+parameters.
While this looks odd, it's perfectly plain and legal Perl syntax. POE
uses it for a few reasons:
@@ -905,23 +906,26 @@ methods in the same object. C<$_[OBJECT]> helps this happen.
$self->update_status_line();
}
-You may also use method inheritance
+You may also use method inheritance. Here we invoke
+$self->a_method(@_). Since Perl's C<<->>> operator unshifts $self
+onto the beginning of @_, we must first shift a copy off to maintain
+POE's parameter offsets:
- sub Amethod {
+ sub a_method {
my $self = shift;
- $self->SUPER::Amethod( @_ );
+ $self->SUPER::a_method( @_ );
# ... more work ...
}
=head3 $_[SESSION]
C<$_[SESSION]> is a reference to the current session object. This lets event
handlers access their session's methods. Programs may also compare
-C<$_[SESSION]> to CL</$_[SENDER]> to verify that intra-session events did not
+C<$_[SESSION]> to C</$_[SENDER]> to verify that intra-session events did not
come from other sessions.
C<$_[SESSION]> may also be used as the destination for intra-session
-CL<post()|POE::Kernel/post> and CL<call()|POE::Kernel/call>. CL<yield()|POE::Kernel/yield> is marginally more convenient and
+C<post()|POE::Kernel/post> and C<call()|POE::Kernel/call>. C<yield()|POE::Kernel/yield> is marginally more convenient and
efficient than C<post($_[SESSION], ...)> however.
It is bad form to access another session directly. The recommended
@@ -1078,7 +1082,7 @@ means anything stored there will be available to any other event
handler regardless of the object.
event_2a is handled by calling C<< $object_2->method_2a(...) >>. In this
-case CL</$_[OBJECT]> is $object_2. C<$_[HEAP]> is the same anonymous hashref
+case C</$_[OBJECT]> is $object_2. C<$_[HEAP]> is the same anonymous hashref
that was passed to the event_1a handler, though. The methods are resolved
when the event is handled (late-binding).

0 comments on commit 9b1c689

Please sign in to comment.