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 { ... }; |
30 |
|
31 |
my $w = AE::cv; # stores whether a condition was flagged |
32 |
$w->send; # wake up current and all future recv's |
33 |
$w->recv; # enters "main loop" till $condvar gets ->send |
34 |
# use a condvar in callback mode: |
35 |
$w->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 it's lack of extensibility, leading to |
44 |
a shorter, easier and faster API. |
45 |
|
46 |
The main difference to AnyEvent is that instead of method calls, function |
47 |
calls are used, 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 compiletime 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 |
At the moment, there will be no checking (L<AnyEvent::Strict> does not |
59 |
affect his API), so the L<AnyEvent> API has a definite advantage here |
60 |
still. |
61 |
|
62 |
Note that the C<AE> API is an alternative to, not the future version of, |
63 |
the AnyEvent API. Both APIs can be used interchangably and and there are |
64 |
no plans to "switch", so if in doubt, feel free to use the L<AnyEvent> |
65 |
API in new code. |
66 |
|
67 |
As the AE API is complementary, not everything in the AnyEvent API is |
68 |
available, so you still need to use AnyEvent for the finer stuff. Also, |
69 |
you should not C<use AE> directly, C<use AnyEvent> will provide the AE |
70 |
namespace. |
71 |
|
72 |
=head2 FUNCTIONS |
73 |
|
74 |
This section briefly describes the alternative watcher |
75 |
constructors. Semantics and any methods are not described here, please |
76 |
refer to 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 |
Example: wait until STDIN becomes readable. |
98 |
|
99 |
$stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> }; |
100 |
|
101 |
Example. wait until STDOUT becomes writable and print something. |
102 |
|
103 |
$stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" }; |
104 |
|
105 |
=item $w = AE::timer $after, $interval, $cb |
106 |
|
107 |
Creates a timer watcher that invokes the callback C<$cb> after at least |
108 |
C<$after> second have passed (C<$after> can be negative or C<0>). |
109 |
|
110 |
If C<$interval> is C<0>, then the clalback will only be invoked once, |
111 |
otherwise it must be a positive number of seconds that specified the |
112 |
interval between successive invocations of the callback. |
113 |
|
114 |
Example: print "too late" after at least one second has passed. |
115 |
|
116 |
$timer_once = AE::timer 1, 0, sub { print "too late\n" }; |
117 |
|
118 |
Example: print "blubb" once a second, starting as soon as possible. |
119 |
|
120 |
$timer_repeated = AE::timer 0, 1, sub { print "blubb\n" }; |
121 |
|
122 |
=item $w = AE::signal $signame, $cb |
123 |
|
124 |
Invoke the callback c<$cb> each time one or more occurences of the named |
125 |
signal C<$signame> are detected. |
126 |
|
127 |
=item $w = AE::child $pid, $cb |
128 |
|
129 |
Invokes the callbakc C<$cb> when the child with the given C<$pid> exits |
130 |
(or all children, when C<$pid> is zero). |
131 |
|
132 |
The callback will get the actual pid and exit status as arguments. |
133 |
|
134 |
=item $w = AE::idle $cb |
135 |
|
136 |
Invoke the callback C<$cb> each time the event loop is "idle" (has no |
137 |
events outstanding), but do not prevent the event loop from polling for |
138 |
more events. |
139 |
|
140 |
=item $cv = AE::cv |
141 |
|
142 |
=item $cv = AE::cv { BLOCK } |
143 |
|
144 |
Create a new condition variable. The first form is identical to C<< |
145 |
AnyEvent->condvar >>, the second form additionally sets the callback (as |
146 |
if the C<cb> method is called on the condition variable). |
147 |
|
148 |
=item AE::now |
149 |
|
150 |
Returns the current event loop time (may be cached by the event loop). |
151 |
|
152 |
=item AE::now_update |
153 |
|
154 |
Ensures that the current event loop time is up to date. |
155 |
|
156 |
=item AE::time |
157 |
|
158 |
Return the current time (not cached, always consults a hardware clock). |
159 |
|
160 |
=back |
161 |
|
162 |
=head1 AUTHOR |
163 |
|
164 |
Marc Lehmann <schmorp@schmorp.de> |
165 |
http://home.schmorp.de/ |
166 |
|
167 |
=cut |
168 |
|
169 |
1 |
170 |
|