--- cvsroot/EV/EV.pm	2007/10/27 07:30:10	1.6
+++ cvsroot/EV/EV.pm	2007/10/29 07:24:37	1.10
@@ -27,7 +27,7 @@
  my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
     my ($w, $events) = @_; # all callbacks get the watcher object and event mask
     if ($events & EV::TIMEOUT) {
-       warn "nothign received on stdin for 10 seconds, retrying";
+       warn "nothing received on stdin for 10 seconds, retrying";
     } else {
        warn "stdin is readable, you entered: ", <STDIN>;
     }
@@ -57,12 +57,12 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '0.01';
+   our $VERSION = '0.02';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
 
-=head1 FUNCTIONAL INTERFACE
+=head1 BASIC INTERFACE
 
 =over 4
 
@@ -70,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.
@@ -103,13 +111,39 @@
 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.
+You can 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::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
+
+=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
+
+Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
+a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
+and will automatically be cleared. The watcher will be restarted after each event.
+
+If the timeout is zero or undef, no timeout will be set, and a normal
+watcher (with the persist flag set!) will be created.
+
+This has the effect of timing out after the specified period of inactivity
+has happened.
+
+Due to the design of libevent, this is also relatively inefficient, having
+one or two io watchers and a separate timeout watcher that you reset on
+activity (by calling its C<start> method) is usually more efficient.
 
 =item my $w = EV::timer $after, $repeat, $callback
 
@@ -140,6 +174,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
@@ -184,7 +222,15 @@
 
 =item $old_fh = $w->fh ($new_fh)
 
-Returns the previously set filehandle and optionally set a new one.
+Returns the previously set filehandle and optionally set a new one (also
+clears the EV::SIGNAL flag when setting a filehandle).
+
+=item $current_signal = $w->signal
+
+=item $old_signal = $w->signal ($new_signal)
+
+Returns the previously set signal number and optionally set a new one (also sets
+the EV::SIGNAL flag when setting a signal).
 
 =item $current_eventmask = $w->events
 
@@ -211,25 +257,22 @@
 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). Since this is such a common issue, this module will
-force the epoll method in EV to be off *unless* the global variable
-$EV::ENABLE_EPOLL is set to 1 *before* loading this module for the first
-time.
+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 $NPRI = 4;
-our $BASE;
-our $ENABLE_EPOLL;
-
-{
-   local $ENV{EVENT_NOEPOLL};
-   $ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
-   $BASE = init;
-}
+our $DIED = sub {
+   warn "EV: error in callback (ignoring): $@";
+};
 
+our $NPRI = 4;
+our $BASE = init;
 priority_init $NPRI;
 
 push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];