--- cvsroot/EV/EV.pm	2007/10/26 17:24:17	1.2
+++ cvsroot/EV/EV.pm	2007/10/27 19:11:27	1.8
@@ -43,7 +43,12 @@
 =head1 DESCRIPTION
 
 This module provides an interface to libevent
-(L<http://monkey.org/~provos/libevent/>).
+(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
+yourself with its documentation and source code to be able to use this
+module fully.
+
+Please note thta this module disables the libevent EPOLL method by
+default, see BUGS, below, if you need to enable it.
 
 =cut
 
@@ -57,7 +62,7 @@
    XSLoader::load "EV", $VERSION;
 }
 
-=head1 FUNCTIONAL INTERFACE
+=head1 BASIC INTERFACE
 
 =over 4
 
@@ -65,6 +70,14 @@
 
 How many priority levels are available.
 
+=item $EV::DIED
+
+Must contain a reference to a function that is called when a callback
+throws an exception (with $@ containing thr error). The default prints an
+informative message and continues.
+
+If this callback throws an exception it will be silently ignored.
+
 =item $time = EV::now
 
 Returns the time in (fractional) seconds since the epoch.
@@ -98,13 +111,21 @@
 when the events specified in C<$eventmask> happen. Initially, the timeout
 is disabled.
 
-The C<io_ns> variant doesn't add/start the newly created watcher.
+Youc an additionall set a timeout to occur on the watcher, but note that
+this timeout will not be reset when you get an I/O event in the EV::PERSIST
+case, and reaching a timeout will always stop the watcher even in the
+EV::PERSIST case.
+
+If you want a timeout to occur only after a specific time of inactivity, set
+a repeating timeout and do NOT use EV::PERSIST.
 
 Eventmask can be one or more of these constants ORed together:
 
   EV::READ     wait until read() wouldn't block anymore
   EV::WRITE    wait until write() wouldn't block anymore
-  EV::PERSIST  stay active after an event occured
+  EV::PERSIST  stay active after a (non-timeout) event occured
+
+The C<io_ns> variant doesn't add/start the newly created watcher.
 
 =item my $w = EV::timer $after, $repeat, $callback
 
@@ -135,6 +156,10 @@
 as long as the processing time is less then the interval (otherwise
 obviously events will be skipped).
 
+Another way to think about it (for the mathematically inclined) is that
+C<timer_abs> will try to tun the callback at the next possible time where
+C<$time = $at (mod $interval)>, regardless of any time jumps.
+
 The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
 
 =item my $w = EV::signal $signum, $callback
@@ -206,14 +231,33 @@
 Lots. Libevent itself isn't well tested and rather buggy, and this module
 is quite new at the moment.
 
+Please note that the epoll method is not, in general, reliable in programs
+that use fork (even if no libveent calls are being made in the forked
+process). If your program behaves erratically, try setting the environment
+variable C<EVENT_NOEPOLL> first when running the program.
+
+In general, if you fork, then you can only use the EV module in one of the
+children.
+
 =cut
 
+our $DIED = sub {
+   warn "EV: error in callback (ignoring): $@";
+};
+
 our $NPRI = 4;
 our $BASE = init;
 priority_init $NPRI;
 
+push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
+
 1;
 
+=head1 SEE ALSO
+
+  L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
+  L<EV::AnyEvent>.
+
 =head1 AUTHOR
 
  Marc Lehmann <schmorp@schmorp.de>