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