--- AnyEvent/lib/AnyEvent.pm	2008/05/25 23:52:02	1.136
+++ AnyEvent/lib/AnyEvent.pm	2008/05/31 13:38:01	1.151
@@ -1,4 +1,4 @@
-=head1 => NAME
+=head1 NAME
 
 AnyEvent - provide framework for multiple event loops
 
@@ -20,6 +20,12 @@
    $w->send; # wake up current and all future recv's
    $w->recv; # enters "main loop" till $condvar gets ->send
 
+=head1 INTRODUCTION/TUTORIAL
+
+This manpage is mainly a reference manual. If you are interested
+in a tutorial or some gentle introduction, have a look at the
+L<AnyEvent::Intro> manpage.
+
 =head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
 
 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
@@ -50,7 +56,7 @@
 
 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
+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
@@ -64,7 +70,13 @@
 offering the functionality that is necessary, in as thin as a wrapper as
 technically possible.
 
-Of course, if you want lots of policy (this can arguably be somewhat
+Of course, AnyEvent comes with a big (and fully optional!) toolbox
+of useful functionality, such as an asynchronous DNS resolver, 100%
+non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
+such as Windows) and lots of real-world knowledge and workarounds for
+platform bugs and differences.
+
+Now, if you I<do want> lots of policy (this can arguably be somewhat
 useful) and you want to force your users to use the one and only event
 model, you should I<not> use this module.
 
@@ -104,7 +116,7 @@
 
 The pure-perl implementation of AnyEvent is called
 C<AnyEvent::Impl::Perl>. Like other event modules you can load it
-explicitly.
+explicitly and enjoy the high availability of that event loop :)
 
 =head1 WATCHERS
 
@@ -128,10 +140,10 @@
 
 An any way to achieve that is this pattern:
 
-  my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
-     # you can use $w here, for example to undef it
-     undef $w;
-  });
+   my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
+      # you can use $w here, for example to undef it
+      undef $w;
+   });
 
 Note that C<my $w; $w => combination. This is necessary because in Perl,
 my variables are only visible after the statement in which they are
@@ -229,6 +241,69 @@
 AnyEvent always prefers relative timers, if available, matching the
 AnyEvent API.
 
+AnyEvent has two additional methods that return the "current time":
+
+=over 4
+
+=item AnyEvent->time
+
+This returns the "current wallclock time" as a fractional number of
+seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
+return, and the result is guaranteed to be compatible with those).
+
+It progresses independently of any event loop processing, i.e. each call
+will check the system clock, which usually gets updated frequently.
+
+=item AnyEvent->now
+
+This also returns the "current wallclock time", but unlike C<time>, above,
+this value might change only once per event loop iteration, depending on
+the event loop (most return the same time as C<time>, above). This is the
+time that AnyEvent's timers get scheduled against.
+
+I<In almost all cases (in all cases if you don't care), this is the
+function to call when you want to know the current time.>
+
+This function is also often faster then C<< AnyEvent->time >>, and
+thus the preferred method if you want some timestamp (for example,
+L<AnyEvent::Handle> uses this to update it's activity timeouts).
+
+The rest of this section is only of relevance if you try to be very exact
+with your timing, you can skip it without bad conscience.
+
+For a practical example of when these times differ, consider L<Event::Lib>
+and L<EV> and the following set-up:
+
+The event loop is running and has just invoked one of your callback at
+time=500 (assume no other callbacks delay processing). In your callback,
+you wait a second by executing C<sleep 1> (blocking the process for a
+second) and then (at time=501) you create a relative timer that fires
+after three seconds.
+
+With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
+both return C<501>, because that is the current time, and the timer will
+be scheduled to fire at time=504 (C<501> + C<3>).
+
+With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
+time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
+last event processing phase started. With L<EV>, your timer gets scheduled
+to run at time=503 (C<500> + C<3>).
+
+In one sense, L<Event::Lib> is more exact, as it uses the current time
+regardless of any delays introduced by event processing. However, most
+callbacks do not expect large delays in processing, so this causes a
+higher drift (and a lot more system calls to get the current time).
+
+In another sense, L<EV> is more exact, as your timer will be scheduled at
+the same time, regardless of how long event processing actually took.
+
+In either case, if you care (and in most cases, you don't), then you
+can get whatever behaviour you want with any event loop, by taking the
+difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
+account.
+
+=back
+
 =head2 SIGNAL WATCHERS
 
 You can watch for signals using a signal watcher, C<signal> is the signal
@@ -279,21 +354,21 @@
 
 Example: fork a process and wait for it
 
-  my $done = AnyEvent->condvar;
-
-  my $pid = fork or exit 5;
-
-  my $w = AnyEvent->child (
-     pid => $pid,
-     cb  => sub {
-        my ($pid, $status) = @_;
-        warn "pid $pid exited with status $status";
-        $done->send;
-     },
-  );
-
-  # do something else, then wait for process exit
-  $done->recv;
+   my $done = AnyEvent->condvar;
+  
+   my $pid = fork or exit 5;
+  
+   my $w = AnyEvent->child (
+      pid => $pid,
+      cb  => sub {
+         my ($pid, $status) = @_;
+         warn "pid $pid exited with status $status";
+         $done->send;
+      },
+   );
+  
+   # do something else, then wait for process exit
+   $done->recv;
 
 =head2 CONDITION VARIABLES
 
@@ -524,8 +599,9 @@
 replaces it before doing so.
 
 The callback will be called when the condition becomes "true", i.e. when
-C<send> or C<croak> are called. Calling C<recv> inside the callback
-or at any later time is guaranteed not to block.
+C<send> or C<croak> are called, with the only argument being the condition
+variable itself. Calling C<recv> inside the callback or at any later time
+is guaranteed not to block.
 
 =back
 
@@ -733,7 +809,7 @@
 
 use Carp;
 
-our $VERSION = '4.03';
+our $VERSION = 4.11;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -741,6 +817,13 @@
 
 our @REGISTRY;
 
+our $WIN32;
+
+BEGIN {
+   my $win32 = ! ! ($^O =~ /mswin32/i);
+   eval "sub WIN32(){ $win32 }";
+}
+
 our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
 
 our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
@@ -768,7 +851,7 @@
    [Prima::                => AnyEvent::Impl::POE::],
 );
 
-our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
+our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
 
 our @post_detect;
 
@@ -795,6 +878,7 @@
 sub detect() {
    unless ($MODEL) {
       no strict 'refs';
+      local $SIG{__DIE__};
 
       if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
          my $model = "AnyEvent::Impl::$1";
@@ -861,6 +945,13 @@
 
 package AnyEvent::Base;
 
+# default implementation for now and time
+
+use Time::HiRes ();
+
+sub time { Time::HiRes::time }
+sub now  { Time::HiRes::time }
+
 # default implementation for ->condvar
 
 sub condvar {
@@ -927,7 +1018,7 @@
    $PID_CB{$pid}{$arg{cb}} = $arg{cb};
 
    unless ($WNOHANG) {
-      $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
+      $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
    }
 
    unless ($CHLD_W) {
@@ -1084,7 +1175,7 @@
 For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
 could start your program like this:
 
-  PERL_ANYEVENT_MODEL=Perl perl ...
+   PERL_ANYEVENT_MODEL=Perl perl ...
 
 =item C<PERL_ANYEVENT_PROTOCOLS>
 
@@ -1117,6 +1208,11 @@
 Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
 EDNS0 in its DNS requests.
 
+=item C<PERL_ANYEVENT_MAX_FORKS>
+
+The maximum number of child processes that C<AnyEvent::Util::fork_call>
+will create in parallel.
+
 =back
 
 =head1 EXAMPLE PROGRAM
@@ -1564,9 +1660,9 @@
 You can make AnyEvent completely ignore this variable by deleting it
 before the first watcher gets created, e.g. with a C<BEGIN> block:
 
-  BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
-
-  use AnyEvent;
+   BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
+  
+   use AnyEvent;
 
 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
@@ -1597,8 +1693,8 @@
 
 =head1 AUTHOR
 
- Marc Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   Marc Lehmann <schmorp@schmorp.de>
+   http://home.schmorp.de/
 
 =cut