| 1 |
=head1 NAME |
| 2 |
|
| 3 |
AE - simpler/faster/newer/cooler AnyEvent API |
| 4 |
|
| 5 |
=head1 SYNOPSIS |
| 6 |
|
| 7 |
use AnyEvent; # not AE |
| 8 |
|
| 9 |
# file handle or descriptor readable |
| 10 |
my $w = AE::io $fh, 0, sub { ... }; |
| 11 |
|
| 12 |
# one-shot or repeating timers |
| 13 |
my $w = AE::timer $seconds, 0, sub { ... }; # once |
| 14 |
my $w = AE::timer $seconds, $interval, sub { ... }; # repeated |
| 15 |
|
| 16 |
print AE::now; # prints current event loop time |
| 17 |
print AE::time; # think Time::HiRes::time or simply CORE::time. |
| 18 |
|
| 19 |
# POSIX signal |
| 20 |
my $w = AE::signal TERM => sub { ... }; |
| 21 |
|
| 22 |
# child process exit |
| 23 |
my $w = AE::child $pid, sub { |
| 24 |
my ($pid, $status) = @_; |
| 25 |
... |
| 26 |
}; |
| 27 |
|
| 28 |
# called when event loop idle (if applicable) |
| 29 |
my $w = AE::idle sub { ... }; |
| 30 |
|
| 31 |
my $cv = AE::cv; # stores whether a condition was flagged |
| 32 |
$cv->send; # wake up current and all future recv's |
| 33 |
$cv->recv; # enters "main loop" till $condvar gets ->send |
| 34 |
# use a condvar in callback mode: |
| 35 |
$cv->cb (sub { $_[0]->recv }); |
| 36 |
|
| 37 |
|
| 38 |
=head1 DESCRIPTION |
| 39 |
|
| 40 |
This module documents the new simpler AnyEvent API. |
| 41 |
|
| 42 |
The rationale for the new API is that experience with L<EV> shows that |
| 43 |
this API actually "works", despite its lack of extensibility, leading to |
| 44 |
a shorter, easier and faster API. |
| 45 |
|
| 46 |
The main differences from AnyEvent is that function calls are used |
| 47 |
instead of method calls, and that no named arguments are used. |
| 48 |
|
| 49 |
This makes calls to watcher creation functions really short, which can |
| 50 |
make a program more readable despite the lack of named parameters. |
| 51 |
Function calls also allow more static type checking than method calls, so |
| 52 |
many mistakes are caught at compile-time with this API. |
| 53 |
|
| 54 |
Also, some backends (Perl and EV) are so fast that the method call |
| 55 |
overhead is very noticeable (with EV it increases the execution time five- |
| 56 |
to six-fold, with Perl the method call overhead is about a factor of two). |
| 57 |
|
| 58 |
Note that the C<AE> API is an alternative to, not the future version of, |
| 59 |
the AnyEvent API. Both APIs can be used interchangeably and there are |
| 60 |
no plans to "switch", so if in doubt, feel free to use the L<AnyEvent> |
| 61 |
API in new code. |
| 62 |
|
| 63 |
As the AE API is complementary, not everything in the AnyEvent API is |
| 64 |
available, and you still need to use AnyEvent for the finer stuff. Also, |
| 65 |
you should not C<use AE> directly, C<use AnyEvent> will provide the AE |
| 66 |
namespace. |
| 67 |
|
| 68 |
At the moment, these functions will become slower then their method-call |
| 69 |
counterparts when using L<AnyEvent::Strict> or L<AnyEvent::Debug>::wrap. |
| 70 |
|
| 71 |
=head2 FUNCTIONS |
| 72 |
|
| 73 |
This section briefly describes the alternative watcher constructors and |
| 74 |
other functions available inside the C<AE> namespace. Semantics are not |
| 75 |
described here; please refer to the description of the function or method |
| 76 |
with the same name in the L<AnyEvent> manpage for the details. |
| 77 |
|
| 78 |
=over 4 |
| 79 |
|
| 80 |
=cut |
| 81 |
|
| 82 |
package AE; |
| 83 |
|
| 84 |
use AnyEvent (); # BEGIN { AnyEvent::common_sense } |
| 85 |
|
| 86 |
our $VERSION = $AnyEvent::VERSION; |
| 87 |
|
| 88 |
=item $w = AE::io $fh_or_fd, $watch_write, $cb |
| 89 |
|
| 90 |
Creates an I/O watcher that listens for read events (C<$watch_write> |
| 91 |
false) or write events (C<$watch_write> is true) on the file handle or |
| 92 |
file descriptor C<$fh_or_fd>. |
| 93 |
|
| 94 |
The callback C<$cb> is invoked as soon and as long as I/O of the type |
| 95 |
specified by C<$watch_write>) can be done on the file handle/descriptor. |
| 96 |
|
| 97 |
If you want a mnemomic for the second argument: C<0> is standard I<input>, |
| 98 |
for I<reading>, and C<1> is standard I<output>, for I<writing>. |
| 99 |
|
| 100 |
Example: wait until STDIN becomes readable. |
| 101 |
|
| 102 |
$stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> }; |
| 103 |
|
| 104 |
Example: wait until STDOUT becomes writable and print something. |
| 105 |
|
| 106 |
$stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" }; |
| 107 |
|
| 108 |
=item $w = AE::timer $after, $interval, $cb |
| 109 |
|
| 110 |
Creates a timer watcher that invokes the callback C<$cb> after at least |
| 111 |
C<$after> second have passed (C<$after> can be negative or C<0>). |
| 112 |
|
| 113 |
If C<$interval> is C<0>, then the callback will only be invoked once, |
| 114 |
otherwise it must be a positive number of seconds that specifies the |
| 115 |
interval between successive invocations of the callback. |
| 116 |
|
| 117 |
Example: print "too late" after at least one second has passed. |
| 118 |
|
| 119 |
$timer_once = AE::timer 1, 0, sub { print "too late\n" }; |
| 120 |
|
| 121 |
Example: print "blubb" once a second, starting as soon as possible. |
| 122 |
|
| 123 |
$timer_repeated = AE::timer 0, 1, sub { print "blubb\n" }; |
| 124 |
|
| 125 |
=item $w = AE::signal $signame, $cb |
| 126 |
|
| 127 |
Invoke the callback C<$cb> each time one or more occurrences of the |
| 128 |
named signal C<$signame> are detected. |
| 129 |
|
| 130 |
=item $w = AE::child $pid, $cb |
| 131 |
|
| 132 |
Invokes the callback C<$cb> when the child with the given C<$pid> exits |
| 133 |
(or all children, when C<$pid> is zero). |
| 134 |
|
| 135 |
The callback will get the actual pid and exit status as arguments. |
| 136 |
|
| 137 |
=item $w = AE::idle $cb |
| 138 |
|
| 139 |
Invoke the callback C<$cb> each time the event loop is "idle" (has no |
| 140 |
events outstanding), but do not prevent the event loop from polling for |
| 141 |
more events. |
| 142 |
|
| 143 |
=item $cv = AE::cv |
| 144 |
|
| 145 |
=item $cv = AE::cv { BLOCK } |
| 146 |
|
| 147 |
Create a new condition variable. The first form is identical to C<< |
| 148 |
AnyEvent->condvar >>, the second form additionally sets the callback (as |
| 149 |
if the C<cb> method is called on the condition variable). |
| 150 |
|
| 151 |
=item AE::now |
| 152 |
|
| 153 |
Returns the current event loop time (may be cached by the event loop). |
| 154 |
|
| 155 |
=item AE::now_update |
| 156 |
|
| 157 |
Ensures that the current event loop time is up to date. |
| 158 |
|
| 159 |
=item AE::time |
| 160 |
|
| 161 |
Return the current time (not cached, always consults a hardware clock). |
| 162 |
|
| 163 |
=item AE::postpone { BLOCK } |
| 164 |
|
| 165 |
Exactly the same as C<AnyEvent:::postpone>. |
| 166 |
|
| 167 |
=item AE::log $level, $msg[, @args] |
| 168 |
|
| 169 |
Exactly the same as C<AnyEvent::log> (or C<AnyEvent::Log::log>). |
| 170 |
|
| 171 |
=back |
| 172 |
|
| 173 |
=head1 AUTHOR |
| 174 |
|
| 175 |
Marc Lehmann <schmorp@schmorp.de> |
| 176 |
http://anyevent.schmorp.de |
| 177 |
|
| 178 |
=cut |
| 179 |
|
| 180 |
1 |
| 181 |
|
