--- AnyEvent/lib/AnyEvent.pm	2008/05/27 02:34:30	1.142
+++ AnyEvent/lib/AnyEvent.pm	2008/05/31 00:40:16	1.148
@@ -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
@@ -235,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
@@ -739,7 +808,7 @@
 
 use Carp;
 
-our $VERSION = '4.05';
+our $VERSION = 4.11;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -781,7 +850,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;
 
@@ -875,6 +944,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 {