--- cvsroot/EV/EV.pm	2007/11/21 05:09:38	1.43
+++ cvsroot/EV/EV.pm	2007/11/24 08:28:10	1.49
@@ -59,12 +59,12 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '1.1';
+   our $VERSION = '1.2';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
 
-@EV::Io::ISA       =
+@EV::IO::ISA       =
 @EV::Timer::ISA    =
 @EV::Periodic::ISA =
 @EV::Signal::ISA   =
@@ -119,6 +119,29 @@
 When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
 fast as possible.
 
+=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
+
+This function rolls together an I/O and a timer watcher for a single
+one-shot event without the need for managing a watcher object.
+
+If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
+must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
+| EV::WRITE>, indicating the type of I/O event you want to wait for. If
+you do not want to wait for some I/O event, specify C<undef> for
+C<$fh_or_undef> and C<0> for C<$events>).
+
+If timeout is C<undef> or negative, then there will be no
+timeout. Otherwise a EV::timer with this value will be started.
+
+When an error occurs or either the timeout or I/O watcher triggers, then
+the callback will be called with the received event set (in general
+you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
+C<EV::WRITE> and C<EV::TIMEOUT>).
+
+EV::once doesn't return anything: the watchers stay active till either
+of them triggers, then they will be stopped and freed, and the callback
+invoked.
+
 =back
 
 =head2 WATCHER
@@ -495,28 +518,30 @@
          or return;
 
       # make the dispatcher handle any outstanding stuff
+      ... not shown
 
       # create an IO watcher for each and every socket
       @snmp_watcher = (
          (map { EV::io $_, EV::READ, sub { } }
              keys %{ $dispatcher->{_descriptors} }),
-      );
 
-      # if there are any timeouts, also create a timer
-      push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
-         if $event->[Net::SNMP::Dispatcher::_ACTIVE];
+         EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
+                     ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
+                    0, sub { },
+      );
    };
 
-The callbacks are irrelevant, the only purpose of those watchers is
-to wake up the process as soon as one of those events occurs (socket
-readable, or timer timed out). The corresponding EV::check watcher will then
-clean up:
+The callbacks are irrelevant (and are not even being called), the
+only purpose of those watchers is to wake up the process as soon as
+one of those events occurs (socket readable, or timer timed out). The
+corresponding EV::check watcher will then clean up:
 
    our $snmp_check = EV::check sub {
       # destroy all watchers
       @snmp_watcher = ();
 
       # make the dispatcher handle any new stuff
+      ... not shown
    };
 
 The callbacks of the created watchers will not be called as the watchers
@@ -529,8 +554,26 @@
 
 =head1 THREADS
 
-Threads are not supported by this in any way. Perl pseudo-threads is evil
-stuff and must die.
+Threads are not supported by this module in any way. Perl pseudo-threads
+is evil stuff and must die. As soon as Perl gains real threads I will work
+on thread support for it.
+
+=head1 FORK
+
+Most of the "improved" event delivering mechanisms of modern operating
+systems have quite a few problems with fork(2) (to put it bluntly: it is
+not supported and usually destructive). Libev makes it possible to work
+around this by having a function that recreates the kernel state after
+fork in the child.
+
+On non-win32 platforms, this module requires the pthread_atfork
+functionality to do this automatically for you. This function is quite
+buggy on most BSDs, though, so YMMV. The overhead for this is quite
+negligible, because everything the function currently does is set a flag
+that is checked only when the event loop gets used the next time, so when
+you do fork but not use EV, the overhead is minimal.
+
+On win32, there is no notion of fork so all this doesn't apply, of course.
 
 =cut