--- AnyEvent/lib/AnyEvent.pm	2005/12/19 17:03:29	1.6
+++ AnyEvent/lib/AnyEvent.pm	2006/07/20 01:32:11	1.11
@@ -6,33 +6,39 @@
 
 =head1 SYNOPSIS
 
-use AnyEvent;
+   use AnyEvent;
 
    my $w = AnyEvent->io (fh => ..., poll => "[rw]+", cb => sub {
       my ($poll_got) = @_;
       ...
    });
 
-- only one io watcher per $fh and $poll type is allowed
-(i.e. on a socket you can have one r + one w or one rw
-watcher, not any more.
+* only one io watcher per $fh and $poll type is allowed (i.e. on a socket
+you can have one r + one w or one rw watcher, not any more (limitation by
+Tk).
+
+* the C<$poll_got> passed to the handler needs to be checked by looking
+for single characters (e.g. with a regex), as it can contain more event
+types than were requested (e.g. a 'w' watcher might generate 'rw' events,
+limitation by Glib).
 
-- AnyEvent will keep filehandles alive, so as long as the watcher exists,
+* AnyEvent will keep filehandles alive, so as long as the watcher exists,
 the filehandle exists.
 
    my $w = AnyEvent->timer (after => $seconds, cb => sub {
       ...
    });
 
-- io and time watchers get canceled whenever $w is destroyed, so keep a copy
+* io and time watchers get canceled whenever $w is destroyed, so keep a copy
 
-- timers can only be used once and must be recreated for repeated operation
+* timers can only be used once and must be recreated for repeated
+operation (limitation by Glib and Tk).
 
    my $w = AnyEvent->condvar; # kind of main loop replacement
    $w->wait; # enters main loop till $condvar gets ->broadcast
    $w->broadcast; # wake up current and all future wait's
 
-- condvars are used to give blocking behaviour when neccessary. Create
+* condvars are used to give blocking behaviour when neccessary. Create
 a condvar for any "request" or "event" your module might create, C<<
 ->broadcast >> it when the event happens and provide a function that calls
 C<< ->wait >> for it. See the examples below.
@@ -64,17 +70,21 @@
 use strict 'vars';
 use Carp;
 
-our $VERSION = 0.3;
+our $VERSION = '1.02';
 our $MODEL;
 
 our $AUTOLOAD;
 our @ISA;
 
+our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
+
+our @REGISTRY;
+
 my @models = (
-      [Coro  => Coro::Event::],
-      [Event => Event::],
-      [Glib  => Glib::],
-      [Tk    => Tk::],
+      [Coro::Event:: => AnyEvent::Impl::Coro::],
+      [Event::       => AnyEvent::Impl::Event::],
+      [Glib::        => AnyEvent::Impl::Glib::],
+      [Tk::          => AnyEvent::Impl::Tk::],
 );
 
 our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);
@@ -87,21 +97,27 @@
 
    unless ($MODEL) {
       # check for already loaded models
-      for (@models) {
-         my ($model, $package) = @$_;
-         if (scalar keys %{ *{"$package\::"} }) {
-            eval "require AnyEvent::Impl::$model";
-            last if $MODEL;
+      for (@REGISTRY, @models) {
+         my ($package, $model) = @$_;
+         if (${"$package\::VERSION"} > 0) {
+            if (eval "require $model") {
+               $MODEL = $model;
+               warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
+               last;
+            }
          }
       }
 
       unless ($MODEL) {
          # try to load a model
 
-         for (@models) {
-            my ($model, $package) = @$_;
-            eval "require AnyEvent::Impl::$model";
-            last if $MODEL;
+         for (@REGISTRY, @models) {
+            my ($package, $model) = @$_;
+            if (eval "require $model") {
+               $MODEL = $model;
+               warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
+               last;
+            }
          }
 
          $MODEL
@@ -117,6 +133,37 @@
 
 =back
 
+=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
+
+If you need to support another event library which isn't directly
+supported by AnyEvent, you can supply your own interface to it by
+pushing, before the first watcher gets created, the package name of
+the event module and the package name of the interface to use onto
+C<@AnyEvent::REGISTRY>. You can do that before and even without loading
+AnyEvent.
+
+Example:
+
+   push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
+
+This tells AnyEvent to (literally) use the C<urxvt::anyevent::> module
+when it finds the C<urxvt> module is loaded. When AnyEvent is loaded and
+requested to find a suitable event model, it will first check for the
+urxvt module.
+
+The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt) uses
+the above line exactly. An interface isn't included in AnyEvent
+because it doesn't make sense outside the embedded interpreter inside
+I<rxvt-unicode>, and it is updated and maintained as part of the
+I<rxvt-unicode> distribution.
+
+=head1 ENVIRONMENT VARIABLES
+
+The following environment variables are used by this module:
+
+C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, reports which event
+model gets used.
+
 =head1 EXAMPLE
 
 The following program uses an io watcher to read data from stdin, a timer