ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AE.pm
(Generate patch)

Comparing AnyEvent/lib/AE.pm (file contents):
Revision 1.2 by root, Sun Aug 9 15:09:28 2009 UTC vs.
Revision 1.18 by root, Sun Jul 12 16:31:59 2020 UTC

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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines