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.1 by root, Thu Jul 30 03:41:56 2009 UTC vs.
Revision 1.6 by root, Wed Mar 24 21:22:57 2010 UTC

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

Diff Legend

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