--- AnyEvent/lib/AnyEvent.pm	2008/05/28 23:57:38	1.143
+++ AnyEvent/lib/AnyEvent.pm	2008/07/08 19:50:25	1.164
@@ -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
@@ -166,9 +172,9 @@
 always use non-blocking calls when reading/writing from/to your file
 handles.
 
-Example:
+Example: wait for readability of STDIN, then read a line and disable the
+watcher.
 
-   # wait for readability of STDIN, then read a line and disable the watcher
    my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
       chomp (my $input = <STDIN>);
       warn "read: $input\n";
@@ -188,13 +194,17 @@
 presence is undefined and you cannot rely on them. Portable AnyEvent
 callbacks cannot use arguments passed to time watcher callbacks.
 
-The timer callback will be invoked at most once: if you want a repeating
-timer you have to create a new watcher (this is a limitation by both Tk
-and Glib).
+The callback will normally be invoked once only. If you specify another
+parameter, C<interval>, as a positive number, then the callback will be
+invoked regularly at that interval (in fractional seconds) after the first
+invocation.
+
+The callback will be rescheduled before invoking the callback, but no
+attempt is done to avoid timer drift in most backends, so the interval is
+only approximate.
 
-Example:
+Example: fire an event after 7.7 seconds.
 
-   # fire an event after 7.7 seconds
    my $w = AnyEvent->timer (after => 7.7, cb => sub {
       warn "timeout\n";
    });
@@ -202,19 +212,12 @@
    # to cancel the timer:
    undef $w;
 
-Example 2:
+Example 2: fire an event after 0.5 seconds, then roughly every second.
 
-   # fire an event after 0.5 seconds, then roughly every second
-   my $w;
-
-   my $cb = sub {
-      # cancel the old timer while creating a new one
-      $w = AnyEvent->timer (after => 1, cb => $cb);
+   my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
+      warn "timeout\n";
    };
 
-   # start the "loop" by creating the first watcher
-   $w = AnyEvent->timer (after => 0.5, cb => $cb);
-
 =head3 TIMING ISSUES
 
 There are two ways to handle timers: based on real time (relative, "fire
@@ -245,17 +248,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 +281,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 +289,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 +351,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 +596,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
 
@@ -725,20 +737,27 @@
 Contains various utility functions that replace often-used but blocking
 functions such as C<inet_aton> by event-/callback-based versions.
 
-=item L<AnyEvent::Handle>
-
-Provide read and write buffers and manages watchers for reads and writes.
-
 =item L<AnyEvent::Socket>
 
 Provides various utility functions for (internet protocol) sockets,
 addresses and name resolution. Also functions to create non-blocking tcp
 connections or tcp servers, with IPv6 and SRV record support and more.
 
+=item L<AnyEvent::Handle>
+
+Provide read and write buffers, manages watchers for reads and writes,
+supports raw and formatted I/O, I/O queued and fully transparent and
+non-blocking SSL/TLS.
+
 =item L<AnyEvent::DNS>
 
 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.
@@ -747,6 +766,30 @@
 
 The fastest ping in the west.
 
+=item L<AnyEvent::DBI>
+
+Executes L<DBI> requests asynchronously in a proxy process.
+
+=item L<AnyEvent::AIO>
+
+Truly asynchronous I/O, should be in the toolbox of every event
+programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
+together.
+
+=item L<AnyEvent::BDB>
+
+Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
+L<BDB> and AnyEvent together.
+
+=item L<AnyEvent::GPSD>
+
+A non-blocking interface to gpsd, a daemon delivering GPS information.
+
+=item L<AnyEvent::IGS>
+
+A non-blocking interface to the Internet Go Server protocol (used by
+L<App::IGS>).
+
 =item L<Net::IRC3>
 
 AnyEvent based IRC client module family.
@@ -768,17 +811,6 @@
 
 Has special support for AnyEvent via L<Coro::AnyEvent>.
 
-=item L<AnyEvent::AIO>, L<IO::AIO>
-
-Truly asynchronous I/O, should be in the toolbox of every event
-programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
-together.
-
-=item L<AnyEvent::BDB>, L<BDB>
-
-Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
-IO::AIO and AnyEvent together.
-
 =item L<IO::Lambda>
 
 The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
@@ -794,7 +826,7 @@
 
 use Carp;
 
-our $VERSION = '4.05';
+our $VERSION = 4.2;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -966,7 +998,7 @@
 
    delete $SIG_CB{$signal}{$cb};
 
-   $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
+   delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
 }
 
 # default implementation for ->child
@@ -1160,7 +1192,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 +1677,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 +1719,8 @@
 
 =head1 AUTHOR
 
- Marc Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   Marc Lehmann <schmorp@schmorp.de>
+   http://home.schmorp.de/
 
 =cut