[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.142 by root, Tue May 27 02:34:30 2008 UTC vs.
Revision 1.160 by root, Sun Jun 22 12:17:47 2008 UTC

-=head1 => NAME
+=head1 NAME
 AnyEvent - provide framework for multiple event loops
 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
    });
    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
+=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
 nowadays. So what is different about AnyEvent?
 Many watchers either are used with "recursion" (repeating timers for
 example), or need to refer to their watcher object in other ways.
 An any way to achieve that is this pattern:
-  my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
+   my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
-     # you can use $w here, for example to undef it
+      # you can use $w here, for example to undef it
-     undef $w;
+      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
 declared.
 timers.
 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
 I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
 be invoked whenever a signal occurs.
 AnyEvent program, you I<have> to create at least one watcher before you
 C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
 Example: fork a process and wait for it
-  my $done = AnyEvent->condvar;
+   my $done = AnyEvent->condvar;
-  my $pid = fork or exit 5;
+   my $pid = fork or exit 5;
-  my $w = AnyEvent->child (
+   my $w = AnyEvent->child (
-     pid => $pid,
+      pid => $pid,
-     cb  => sub {
+      cb  => sub {
-        my ($pid, $status) = @_;
+         my ($pid, $status) = @_;
-        warn "pid $pid exited with status $status";
+         warn "pid $pid exited with status $status";
-        $done->send;
+         $done->send;
-     },
+      },
-  );
+   );
-  # do something else, then wait for process exit
+   # do something else, then wait for process exit
-  $done->recv;
+   $done->recv;
 =head2 CONDITION VARIABLES
 If you are familiar with some event loops you will know that all of them
 require you to run some blocking "loop", "run" or similar function that
 This is a mutator function that returns the callback set and optionally
 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
+C<send> or C<croak> are called, with the only argument being the condition
-or at any later time is guaranteed not to block.
+variable itself. Calling C<recv> inside the callback or at any later time
+is guaranteed not to block.
 =back
 =head1 GLOBAL VARIABLES AND FUNCTIONS
 =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.
 =item L<AnyEvent::FastPing>
 The fastest ping in the west.
+=item L<AnyEvent::DBI>
+Executes DBI requests asynchronously in a proxy process.
 =item L<Net::IRC3>
 AnyEvent based IRC client module family.
 no warnings;
 use strict;
 use Carp;
-our $VERSION = '4.05';
+our $VERSION = 4.152;
 our $MODEL;
 our $AUTOLOAD;
 our @ISA;
    [POE::Kernel::          => AnyEvent::Impl::POE::],      # lasciate ogni speranza
    [Wx::                   => AnyEvent::Impl::POE::],
    [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;
 sub post_detect(&) {
    my ($cb) = @_;
    $class->$func (@_);
 }
 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 {
    bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
 }
 This functionality might change in future versions.
 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>
 Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
 for IPv4 or IPv6. The default is unspecified (and might change, or be the result
 specified in the variable.
 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} }
+   BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
-  use AnyEvent;
+   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>.
 Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
 =head1 AUTHOR
- Marc Lehmann <schmorp@schmorp.de>
+   Marc Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   http://home.schmorp.de/
 =cut
 1

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.142 by root, Tue May 27 02:34:30 2008 UTC vs. Revision 1.160 by root, Sun Jun 22 12:17:47 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.142 by root, Tue May 27 02:34:30 2008 UTC vs.
Revision 1.160 by root, Sun Jun 22 12:17:47 2008 UTC