.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AE 3"
.TH AE 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
AE \- simpler/faster/newer/cooler AnyEvent API
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use AnyEvent; # not AE
\&
\&  # file handle or descriptor readable
\&  my $w = AE::io $fh, 0, sub { ...  };
\&
\&  # one\-shot or repeating timers
\&  my $w = AE::timer $seconds,         0, sub { ... }; # once
\&  my $w = AE::timer $seconds, $interval, sub { ... }; # repeated
\&
\&  print AE::now;  # prints current event loop time
\&  print AE::time; # think Time::HiRes::time or simply CORE::time.
\&
\&  # POSIX signal
\&  my $w = AE::signal TERM => sub { ... };
\&
\&  # child process exit
\&  my $w = AE::child $pid, sub {
\&     my ($pid, $status) = @_;
\&     ...
\&  };
\&
\&  # called when event loop idle (if applicable)
\&  my $w = AE::idle sub { ... };
\&
\&  my $cv = AE::cv; # stores whether a condition was flagged
\&  $cv\->send; # wake up current and all future recv\*(Aqs
\&  $cv\->recv; # enters "main loop" till $condvar gets \->send
\&  # use a condvar in callback mode:
\&  $cv\->cb (sub { $_[0]\->recv });
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module documents the new simpler AnyEvent API.
.PP
The rationale for the new API is that experience with EV shows that
this API actually "works", despite its lack of extensibility, leading to
a shorter, easier and faster API.
.PP
The main differences from AnyEvent is that function calls are used
instead of method calls, and that no named arguments are used.
.PP
This makes calls to watcher creation functions really short, which can
make a program more readable despite the lack of named parameters.
Function calls also allow more static type checking than method calls, so
many mistakes are caught at compile-time with this API.
.PP
Also, some backends (Perl and EV) are so fast that the method call
overhead is very noticeable (with EV it increases the execution time five\-
to six-fold, with Perl the method call overhead is about a factor of two).
.PP
Note that the \f(CW\*(C`AE\*(C'\fR API is an alternative to, not the future version of,
the AnyEvent API. Both APIs can be used interchangeably and there are
no plans to "switch", so if in doubt, feel free to use the AnyEvent
API in new code.
.PP
As the AE API is complementary, not everything in the AnyEvent API is
available, and you still need to use AnyEvent for the finer stuff. Also,
you should not \f(CW\*(C`use AE\*(C'\fR directly, \f(CW\*(C`use AnyEvent\*(C'\fR will provide the AE
namespace.
.PP
At the moment, these functions will become slower then their method-call
counterparts when using AnyEvent::Strict or AnyEvent::Debug::wrap.
.SS FUNCTIONS
.IX Subsection "FUNCTIONS"
This section briefly describes the alternative watcher constructors and
other functions available inside the \f(CW\*(C`AE\*(C'\fR namespace. Semantics are not
described here; please refer to the description of the function or method
with the same name in the AnyEvent manpage for the details.
.ie n .IP "$w = AE::io $fh_or_fd, $watch_write, $cb" 4
.el .IP "\f(CW$w\fR = AE::io \f(CW$fh_or_fd\fR, \f(CW$watch_write\fR, \f(CW$cb\fR" 4
.IX Item "$w = AE::io $fh_or_fd, $watch_write, $cb"
Creates an I/O watcher that listens for read events (\f(CW$watch_write\fR
false) or write events (\f(CW$watch_write\fR is true) on the file handle or
file descriptor \f(CW$fh_or_fd\fR.
.Sp
The callback \f(CW$cb\fR is invoked as soon and as long as I/O of the type
specified by \f(CW$watch_write\fR) can be done on the file handle/descriptor.
.Sp
Example: wait until STDIN becomes readable.
.Sp
.Vb 1
\&  $stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> };
.Ve
.Sp
Example: wait until STDOUT becomes writable and print something.
.Sp
.Vb 1
\&  $stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\en" };
.Ve
.ie n .IP "$w = AE::timer $after, $interval, $cb" 4
.el .IP "\f(CW$w\fR = AE::timer \f(CW$after\fR, \f(CW$interval\fR, \f(CW$cb\fR" 4
.IX Item "$w = AE::timer $after, $interval, $cb"
Creates a timer watcher that invokes the callback \f(CW$cb\fR after at least
\&\f(CW$after\fR second have passed (\f(CW$after\fR can be negative or \f(CW0\fR).
.Sp
If \f(CW$interval\fR is \f(CW0\fR, then the callback will only be invoked once,
otherwise it must be a positive number of seconds that specifies the
interval between successive invocations of the callback.
.Sp
Example: print "too late" after at least one second has passed.
.Sp
.Vb 1
\&  $timer_once = AE::timer 1, 0, sub { print "too late\en" };
.Ve
.Sp
Example: print "blubb" once a second, starting as soon as possible.
.Sp
.Vb 1
\&  $timer_repeated = AE::timer 0, 1, sub { print "blubb\en" };
.Ve
.ie n .IP "$w = AE::signal $signame, $cb" 4
.el .IP "\f(CW$w\fR = AE::signal \f(CW$signame\fR, \f(CW$cb\fR" 4
.IX Item "$w = AE::signal $signame, $cb"
Invoke the callback \f(CW$cb\fR each time one or more occurrences of the
named signal \f(CW$signame\fR are detected.
.ie n .IP "$w = AE::child $pid, $cb" 4
.el .IP "\f(CW$w\fR = AE::child \f(CW$pid\fR, \f(CW$cb\fR" 4
.IX Item "$w = AE::child $pid, $cb"
Invokes the callback \f(CW$cb\fR when the child with the given \f(CW$pid\fR exits
(or all children, when \f(CW$pid\fR is zero).
.Sp
The callback will get the actual pid and exit status as arguments.
.ie n .IP "$w = AE::idle $cb" 4
.el .IP "\f(CW$w\fR = AE::idle \f(CW$cb\fR" 4
.IX Item "$w = AE::idle $cb"
Invoke the callback \f(CW$cb\fR each time the event loop is "idle" (has no
events outstanding), but do not prevent the event loop from polling for
more events.
.ie n .IP "$cv = AE::cv" 4
.el .IP "\f(CW$cv\fR = AE::cv" 4
.IX Item "$cv = AE::cv"
.PD 0
.ie n .IP "$cv = AE::cv { BLOCK }" 4
.el .IP "\f(CW$cv\fR = AE::cv { BLOCK }" 4
.IX Item "$cv = AE::cv { BLOCK }"
.PD
Create a new condition variable. The first form is identical to \f(CW\*(C`AnyEvent\->condvar\*(C'\fR, the second form additionally sets the callback (as
if the \f(CW\*(C`cb\*(C'\fR method is called on the condition variable).
.IP AE::now 4
.IX Item "AE::now"
Returns the current event loop time (may be cached by the event loop).
.IP AE::now_update 4
.IX Item "AE::now_update"
Ensures that the current event loop time is up to date.
.IP AE::time 4
.IX Item "AE::time"
Return the current time (not cached, always consults a hardware clock).
.IP "AE::postpone { BLOCK }" 4
.IX Item "AE::postpone { BLOCK }"
Exactly the same as \f(CW\*(C`AnyEvent:::postpone\*(C'\fR.
.ie n .IP "AE::log $level, $msg[, @args]" 4
.el .IP "AE::log \f(CW$level\fR, \f(CW$msg\fR[, \f(CW@args\fR]" 4
.IX Item "AE::log $level, $msg[, @args]"
Exactly the same as \f(CW\*(C`AnyEvent::log\*(C'\fR (or \f(CW\*(C`AnyEvent::Log::log\*(C'\fR).
.SH AUTHOR
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://anyevent.schmorp.de
.Ve