--- AnyEvent/lib/AnyEvent.pm	2008/05/28 23:57:38	1.143
+++ AnyEvent/lib/AnyEvent.pm	2008/06/06 10:23:50	1.156
@@ -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
@@ -134,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
@@ -245,17 +251,25 @@
 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.
-
-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.
+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 timers get scheduled against.
+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:
@@ -270,7 +284,7 @@
 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>m C<< AnyEvent->time >> returns C<501> (as that is the current
+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>).
@@ -278,7 +292,7 @@
 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 syscalls to get the current time).
+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.
@@ -340,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
 
@@ -585,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
 
@@ -739,6 +754,11 @@
 
 Provides rich asynchronous DNS resolver capabilities.
 
+=item L<AnyEvent::HTTP>
+
+A simple-to-use HTTP library that is capable of making a lot of concurrent
+HTTP requests.
+
 =item L<AnyEvent::HTTPD>
 
 Provides a simple web application server framework.
@@ -794,7 +814,7 @@
 
 use Carp;
 
-our $VERSION = '4.05';
+our $VERSION = 4.14;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -1160,7 +1180,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>
 
@@ -1645,15 +1665,24 @@
 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
 probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
 
 
+=head1 BUGS
+
+Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
+to work around. If you suffer from memleaks, first upgrade to Perl 5.10
+and check wether the leaks still show up. (Perl 5.10.0 has other annoying
+mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
+pronounced).
+
+
 =head1 SEE ALSO
 
 Utility functions: L<AnyEvent::Util>.
@@ -1678,8 +1707,8 @@
 
 =head1 AUTHOR
 
- Marc Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   Marc Lehmann <schmorp@schmorp.de>
+   http://home.schmorp.de/
 
 =cut