… | |
… | |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | use AnyEvent; # not AE |
7 | use AnyEvent; # not AE |
8 | |
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 | |
9 | =head1 DESCRIPTION |
38 | =head1 DESCRIPTION |
10 | |
39 | |
11 | This module documents the new simpler AnyEvent API. |
40 | This module documents the new simpler AnyEvent API. |
12 | |
41 | |
13 | The rationale for the new API is that experience with L<EV> shows that |
42 | The rationale for the new API is that experience with L<EV> shows that |
14 | this API actually "works", despite it's lack of extensibility. |
43 | this API actually "works", despite its lack of extensibility, leading to |
|
|
44 | a shorter, easier and faster API. |
15 | |
45 | |
16 | The main difference to AnyEvent is that instead of method calls, function |
46 | The main differences from AnyEvent is that function calls are used |
17 | calls are used, and that no named arguments are used. |
47 | instead of method calls, and that no named arguments are used. |
18 | |
48 | |
19 | This makes calls to watcher creation functions really short, which can |
49 | This makes calls to watcher creation functions really short, which can |
20 | make a program more readable, despite the lack of named parameters. |
50 | make a program more readable despite the lack of named parameters. |
21 | Function calls also allow more static type checking than method calls, so |
51 | Function calls also allow more static type checking than method calls, so |
22 | many mistakes are caught at compiletime with this API. |
52 | many mistakes are caught at compile-time with this API. |
23 | |
53 | |
24 | Also, some backends (Perl and EV) are so fast that the method call |
54 | Also, some backends (Perl and EV) are so fast that the method call |
25 | overhead is very noticable (with EV it increases the time five- to |
55 | overhead is very noticeable (with EV it increases the execution time five- |
26 | six-fold, with Perl the method call overhead is about a factor of two). |
56 | to six-fold, with Perl the method call overhead is about a factor of two). |
27 | |
|
|
28 | At the moment, there will be no checking (L<AnyEvent::Strict> does not |
|
|
29 | affect his API), so the L<AnyEvent> API has a definite advantage here |
|
|
30 | still. |
|
|
31 | |
57 | |
32 | Note that the C<AE> API is an alternative to, not the future version of, |
58 | Note that the C<AE> API is an alternative to, not the future version of, |
33 | the AnyEvent API. Both APIs can be used interchangably and and there are |
59 | the AnyEvent API. Both APIs can be used interchangeably and there are |
34 | no plans to "switch", so if in doubt, use L<AnyEvent>'s API. |
60 | no plans to "switch", so if in doubt, feel free to use the L<AnyEvent> |
|
|
61 | API in new code. |
35 | |
62 | |
36 | As the AE API is complementary, not everything in the AnyEvent API is |
63 | As the AE API is complementary, not everything in the AnyEvent API is |
37 | available, so you still need to use AnyEvent for the finer stuff. Also, |
64 | available, and you still need to use AnyEvent for the finer stuff. Also, |
38 | you should not C<use AE> directly, C<use AnyEvent> will provide the AE |
65 | you should not C<use AE> directly, C<use AnyEvent> will provide the AE |
39 | namespace. |
66 | namespace. |
40 | |
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 | |
41 | =head2 FUNCTIONS |
71 | =head2 FUNCTIONS |
42 | |
72 | |
43 | This section briefly describes the alternative watcher |
73 | This section briefly describes the alternative watcher constructors and |
44 | constructors. Semantics and any methods are not described here, please |
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 |
45 | refer to the L<AnyEvent> manpage for the details. |
76 | with the same name in the L<AnyEvent> manpage for the details. |
46 | |
77 | |
47 | =over 4 |
78 | =over 4 |
48 | |
79 | |
49 | =cut |
80 | =cut |
50 | |
81 | |
51 | package AE; |
82 | package AE; |
52 | |
83 | |
53 | use AnyEvent (); # BEGIN { AnyEvent::common_sense } |
84 | use AnyEvent (); # BEGIN { AnyEvent::common_sense } |
|
|
85 | |
|
|
86 | our $VERSION = $AnyEvent::VERSION; |
54 | |
87 | |
55 | =item $w = AE::io $fh_or_fd, $watch_write, $cb |
88 | =item $w = AE::io $fh_or_fd, $watch_write, $cb |
56 | |
89 | |
57 | Creates an I/O watcher that listens for read events (C<$watch_write> |
90 | Creates an I/O watcher that listens for read events (C<$watch_write> |
58 | false) or write events (C<$watch_write> is true) on the file handle or |
91 | false) or write events (C<$watch_write> is true) on the file handle or |
… | |
… | |
63 | |
96 | |
64 | Example: wait until STDIN becomes readable. |
97 | Example: wait until STDIN becomes readable. |
65 | |
98 | |
66 | $stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> }; |
99 | $stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> }; |
67 | |
100 | |
68 | Example. wait until STDOUT becomes writable and print something. |
101 | Example: wait until STDOUT becomes writable and print something. |
69 | |
102 | |
70 | $stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" }; |
103 | $stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" }; |
71 | |
104 | |
72 | =item $w = AE::timer $after, $interval, $cb |
105 | =item $w = AE::timer $after, $interval, $cb |
73 | |
106 | |
74 | Creates a timer watcher that invokes the callback C<$cb> after at least |
107 | Creates a timer watcher that invokes the callback C<$cb> after at least |
75 | C<$after> second have passed (C<$after> can be negative or C<0>). |
108 | C<$after> second have passed (C<$after> can be negative or C<0>). |
76 | |
109 | |
77 | If C<$interval> is C<0>, then the clalback will only be invoked once, |
110 | If C<$interval> is C<0>, then the callback will only be invoked once, |
78 | otherwise it must be a positive number of seconds that specified the |
111 | otherwise it must be a positive number of seconds that specifies the |
79 | interval between successive invocations of the callback. |
112 | interval between successive invocations of the callback. |
80 | |
113 | |
81 | Example: print "too late" after at least one second has passed. |
114 | Example: print "too late" after at least one second has passed. |
82 | |
115 | |
83 | $timer_once = AE::timer 1, 0, sub { print "too late\n" }; |
116 | $timer_once = AE::timer 1, 0, sub { print "too late\n" }; |
… | |
… | |
86 | |
119 | |
87 | $timer_repeated = AE::timer 0, 1, sub { print "blubb\n" }; |
120 | $timer_repeated = AE::timer 0, 1, sub { print "blubb\n" }; |
88 | |
121 | |
89 | =item $w = AE::signal $signame, $cb |
122 | =item $w = AE::signal $signame, $cb |
90 | |
123 | |
91 | Invoke the callback c<$cb> each time one or more occurences of the named |
124 | Invoke the callback C<$cb> each time one or more occurrences of the |
92 | signal C<$signame> are detected. |
125 | named signal C<$signame> are detected. |
93 | |
126 | |
94 | =item $w = AE::child $pid, $cb |
127 | =item $w = AE::child $pid, $cb |
95 | |
128 | |
96 | Invokes the callbakc C<$cb> when the child with the given C<$pid> exits |
129 | Invokes the callback C<$cb> when the child with the given C<$pid> exits |
97 | (or all children, when C<$pid> is zero). |
130 | (or all children, when C<$pid> is zero). |
98 | |
131 | |
99 | The callback will get the actual pid and exit status as arguments. |
132 | The callback will get the actual pid and exit status as arguments. |
100 | |
133 | |
101 | =item $w = AE::idle $cb |
134 | =item $w = AE::idle $cb |
… | |
… | |
122 | |
155 | |
123 | =item AE::time |
156 | =item AE::time |
124 | |
157 | |
125 | Return the current time (not cached, always consults a hardware clock). |
158 | Return the current time (not cached, always consults a hardware clock). |
126 | |
159 | |
|
|
160 | =item AE::postpone { BLOCK } |
|
|
161 | |
|
|
162 | Exactly the same as C<AnyEvent:::postpone>. |
|
|
163 | |
|
|
164 | =item AE::log $level, $msg[, @args] |
|
|
165 | |
|
|
166 | Exactly the same as C<AnyEvent::log> (or C<AnyEvent::Log::log>). |
|
|
167 | |
127 | =back |
168 | =back |
128 | |
169 | |
129 | =head1 AUTHOR |
170 | =head1 AUTHOR |
130 | |
171 | |
131 | Marc Lehmann <schmorp@schmorp.de> |
172 | Marc Lehmann <schmorp@schmorp.de> |
132 | http://home.schmorp.de/ |
173 | http://anyevent.schmorp.de |
133 | |
174 | |
134 | =cut |
175 | =cut |
135 | |
176 | |
136 | 1 |
177 | 1 |
137 | |
178 | |