[poe-commits] SF.net SVN: poe: [2256] trunk/poe/lib/POE/Session.pm

[<rc...@us...>]

Revision: 2256
          http://poe.svn.sourceforge.net/poe/?rev=2256&view=rev
Author:   rcaputo
Date:     2007-12-02 22:45:05 -0800 (Sun, 02 Dec 2007)

Log Message:
-----------
Initial stab at _default docs.

Modified Paths:
--------------
    trunk/poe/lib/POE/Session.pm

Modified: trunk/poe/lib/POE/Session.pm
===================================================================
--- trunk/poe/lib/POE/Session.pm	2007-12-03 01:53:58 UTC (rev 2255)
+++ trunk/poe/lib/POE/Session.pm	2007-12-03 06:45:05 UTC (rev 2256)
@@ -1489,8 +1489,25 @@
 
 =head2 _default
 
-It's perfectly acceptable to post events to a session that cannot
-handle them.  When this occurs, POE::Session tries to redispatch them
+-><- AM HERE
+
+The _default event is a re-thrown version of an event that had no
+handler.  POE::Session determines when an event cannot be dispatched
+to a handler, and it rewraps and rethrows the event within a _default
+event.
+
+POE::Kernel has very little knowledge about the events a session can
+handle.  Therefore it's perfectly acceptable to post events to a
+session that cannot handle them.  In most cases, the unhandled event
+will be silently dropped.  _default allows a session to catch these
+events rather than allow them to be lost.
+
+_default is quite flexible.  It may be used for debugging, or to
+handle dynamically generated event names without pre-defining their
+handlers.  In the latter sense, _default performs analogously to
+Perl's AUTOLOAD.
+
+When this occurs, POE::Session tries to redispatch them
 as _default.  The unhandled event's parameters are wrapped in an array
 reference and passed to _default's event handler in ARG1.  ARG0
 contains the unhandled event's name.
@@ -1503,9 +1520,6 @@
     );
   }
 
--><- AM HERE
-
-
 Quietly discarding events is a feature, but it makes catching mistyped
 event names kind of hard.  There are a couple ways around this: One is
 to define event names as symbolic constants.  Perl will catch typos at


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.