--- AnyEvent/lib/AnyEvent.pm	2008/07/08 23:10:20	1.166
+++ AnyEvent/lib/AnyEvent.pm	2008/08/20 12:37:21	1.176
@@ -8,17 +8,26 @@
 
    use AnyEvent;
 
-   my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
-      ...
-   });
+   my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ...  });
+
+   my $w = AnyEvent->timer (after => $seconds, cb => sub { ...  });
+   my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
+
+   print AnyEvent->now;  # prints current event loop time
+   print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
 
-   my $w = AnyEvent->timer (after => $seconds, cb => sub {
+   my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
+
+   my $w = AnyEvent->child (pid => $pid, cb => sub {
+      my ($pid, $status) = @_;
       ...
    });
 
    my $w = AnyEvent->condvar; # stores whether a condition was flagged
    $w->send; # wake up current and all future recv's
    $w->recv; # enters "main loop" till $condvar gets ->send
+   # use a condvar in callback mode:
+   $w->cb (sub { $_[0]->recv });
 
 =head1 INTRODUCTION/TUTORIAL
 
@@ -35,11 +44,12 @@
 policy> and AnyEvent is I<small and efficient>.
 
 First and foremost, I<AnyEvent is not an event model> itself, it only
-interfaces to whatever event model the main program happens to use in a
+interfaces to whatever event model the main program happens to use, in a
 pragmatic way. For event models and certain classes of immortals alike,
 the statement "there can only be one" is a bitter reality: In general,
 only one event loop can be active at the same time in a process. AnyEvent
-helps hiding the differences between those event loops.
+cannot change this, but it can hide the differences between those event
+loops.
 
 The goal of AnyEvent is to offer module authors the ability to do event
 programming (waiting for I/O or timer events) without subscribing to a
@@ -50,18 +60,18 @@
 For modules like POE or IO::Async (which is a total misnomer as it is
 actually doing all I/O I<synchronously>...), using them in your module is
 like joining a cult: After you joined, you are dependent on them and you
-cannot use anything else, as it is simply incompatible to everything that
-isn't itself. What's worse, all the potential users of your module are
-I<also> forced to use the same event loop you use.
+cannot use anything else, as they are simply incompatible to everything
+that isn't them. What's worse, all the potential users of your
+module are I<also> forced to use the same event loop you use.
 
 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
 your module uses one of those, every user of your module has to use it,
 too. But if your module uses AnyEvent, it works transparently with all
-event models it supports (including stuff like POE and IO::Async, as long
-as those use one of the supported event loops. It is trivial to add new
-event loops to AnyEvent, too, so it is future-proof).
+event models it supports (including stuff like IO::Async, as long as those
+use one of the supported event loops. It is trivial to add new event loops
+to AnyEvent, too, so it is future-proof).
 
 In addition to being free of having to use I<the one and only true event
 model>, AnyEvent also is free of bloat and policy: with POE or similar
@@ -305,8 +315,8 @@
 =head2 SIGNAL WATCHERS
 
 You can watch for signals using a signal watcher, C<signal> is the signal
-I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
-be invoked whenever a signal occurs.
+I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
+callback to be invoked whenever a signal occurs.
 
 Although the callback might get passed parameters, their value and
 presence is undefined and you cannot rely on them. Portable AnyEvent
@@ -382,8 +392,10 @@
 
 Condition variables can be created by calling the C<< AnyEvent->condvar
 >> method, usually without arguments. The only argument pair allowed is
+
 C<cb>, which specifies a callback to be called when the condition variable
-becomes true.
+becomes true, with the condition variable as the first argument (but not
+the results).
 
 After creation, the condition variable is "false" until it becomes "true"
 by calling the C<send> method (or calling the condition variable as if it
@@ -449,6 +461,23 @@
    my $delay = AnyEvent->timer (after => 5, cb => $done);
    $done->recv;
 
+Example: Imagine an API that returns a condvar and doesn't support
+callbacks. This is how you make a synchronous call, for example from
+the main program:
+
+   use AnyEvent::CouchDB;
+
+   ...
+
+   my @info = $couchdb->info->recv;
+
+And this is how you would just ste a callback to be called whenever the
+results are available:
+
+   $couchdb->info->cb (sub {
+      my @info = $_[0]->recv;
+   });
+
 =head3 METHODS FOR PRODUCERS
 
 These methods should only be used by the producing side, i.e. the
@@ -591,7 +620,7 @@
 Returns true when the condition is "true", i.e. whether C<send> or
 C<croak> have been called.
 
-=item $cb = $cv->cb ([new callback])
+=item $cb = $cv->cb ($cb->($cv))
 
 This is a mutator function that returns the callback set and optionally
 replaces it before doing so.
@@ -827,7 +856,7 @@
 
 use Carp;
 
-our $VERSION = 4.2;
+our $VERSION = 4.231;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -940,9 +969,12 @@
          }
       }
 
-      unshift @ISA, $MODEL;
       push @{"$MODEL\::ISA"}, "AnyEvent::Base";
 
+      unshift @ISA, $MODEL;
+
+      require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
+
       (shift @post_detect)->() while @post_detect;
    }
 
@@ -961,6 +993,27 @@
    $class->$func (@_);
 }
 
+# utility function to dup a filehandle. this is used by many backends
+# to support binding more than one watcher per filehandle (they usually
+# allow only one watcher per fd, so we dup it to get a different one).
+sub _dupfh($$$$) {
+   my ($poll, $fh, $r, $w) = @_;
+
+   require Fcntl;
+
+   # cygwin requires the fh mode to be matching, unix doesn't
+   my ($rw, $mode) = $poll eq "r" ? ($r, "<")
+                   : $poll eq "w" ? ($w, ">")
+                   : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
+
+   open my $fh2, "$mode&" . fileno $fh
+      or die "cannot dup() filehandle: $!";
+
+   # we assume CLOEXEC is already set by perl in all important cases
+
+   ($fh2, $rw)
+}
+
 package AnyEvent::Base;
 
 # default implementation for now and time
@@ -1179,6 +1232,19 @@
 When set to C<2> or higher, cause AnyEvent to report to STDERR which event
 model it chooses.
 
+=item C<PERL_ANYEVENT_STRICT>
+
+AnyEvent does not do much argument checking by default, as thorough
+argument checking is very costly. Setting this variable to a true value
+will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
+check the arguments passed to most method calls. If it finds any problems
+it will croak.
+
+In other words, enables "strict" mode.
+
+Unlike C<use strict> it is definitely recommended ot keep it off in
+production.
+
 =item C<PERL_ANYEVENT_MODEL>
 
 This can be used to specify the event model to be used by AnyEvent, before
@@ -1684,7 +1750,8 @@
 
 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
 be used to probe what backend is used and gain other information (which is
-probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
+probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
+$ENV{PERL_ANYEGENT_STRICT}.
 
 
 =head1 BUGS