AnyEvent/lib/AE.pm

=head1 NAME

AE - simpler/faster/newer/cooler AnyEvent API

=head1 SYNOPSIS

  use AnyEvent; # not AE

=head1 DESCRIPTION

This module documents the new simpler AnyEvent API.

The rationale for the new API is that experience with L<EV> shows that
this API actually "works", despite it's lack of extensibility, leading to
a shorter, easier and faster API.

The main difference to AnyEvent is that instead of method calls, function
calls are used, and that no named arguments are used.

This makes calls to watcher creation functions really short, which can
make a program more readable, despite the lack of named parameters.
Function calls also allow more static type checking than method calls, so
many mistakes are caught at compiletime with this API.

Also, some backends (Perl and EV) are so fast that the method call
overhead is very noticable (with EV it increases the time five- to
six-fold, with Perl the method call overhead is about a factor of two).

At the moment, there will be no checking (L<AnyEvent::Strict> does not
affect his API), so the L<AnyEvent> API has a definite advantage here
still.

Note that the C<AE> API is an alternative to, not the future version of,
the AnyEvent API. Both APIs can be used interchangably and and there are
no plans to "switch", so if in doubt, use the L<AnyEvent> API.

As the AE API is complementary, not everything in the AnyEvent API is
available, so you still need to use AnyEvent for the finer stuff. Also,
you should not C<use AE> directly, C<use AnyEvent> will provide the AE
namespace.

=head2 FUNCTIONS

This section briefly describes the alternative watcher
constructors. Semantics and any methods are not described here, please
refer to the L<AnyEvent> manpage for the details.

=over 4

=cut

package AE;

use AnyEvent (); # BEGIN { AnyEvent::common_sense }

=item $w = AE::io $fh_or_fd, $watch_write, $cb

Creates an I/O watcher that listens for read events (C<$watch_write>
false) or write events (C<$watch_write> is true) on the file handle or
file descriptor C<$fh_or_fd>.

The callback C<$cb> is invoked as soon and as long as I/O of the type
specified by C<$watch_write>) can be done on the file handle/descriptor.

Example: wait until STDIN becomes readable.

  $stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> };

Example. wait until STDOUT becomes writable and print something.

  $stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" };

=item $w = AE::timer $after, $interval, $cb

Creates a timer watcher that invokes the callback C<$cb> after at least
C<$after> second have passed (C<$after> can be negative or C<0>).

If C<$interval> is C<0>, then the clalback will only be invoked once,
otherwise it must be a positive number of seconds that specified the
interval between successive invocations of the callback.

Example: print "too late" after at least one second has passed.

  $timer_once = AE::timer 1, 0, sub { print "too late\n" };

Example: print "blubb" once a second, starting as soon as possible.

  $timer_repeated = AE::timer 0, 1, sub { print "blubb\n" };

=item $w = AE::signal $signame, $cb

Invoke the callback c<$cb> each time one or more occurences of the named
signal C<$signame> are detected.

=item $w = AE::child $pid, $cb

Invokes the callbakc C<$cb> when the child with the given C<$pid> exits
(or all children, when C<$pid> is zero).

The callback will get the actual pid and exit status as arguments.

=item $w = AE::idle $cb

Invoke the callback C<$cb> each time the event loop is "idle" (has no
events outstanding), but do not prevent the event loop from polling for
more events.

=item $cv = AE::cv

=item $cv = AE::cv { BLOCK }

Create a new condition variable. The first form is identical to C<<
AnyEvent->condvar >>, the second form additionally sets the callback (as
if the C<cb> method is called on the condition variable).

=item AE::now

Returns the current event loop time (may be cached by the event loop).

=item AE::now_update

Ensures that the current event loop time is up to date.

=item AE::time

Return the current time (not cached, always consults a hardware clock).

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.3
Committed:	Sun Aug 9 16:11:05 2009 UTC (14 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-5_21, rel-5_12, rel-5_1, rel-5_2, rel-5_22, rel-5_201, rel-5_202, rel-5_11, rel-5_01, rel-5_111, rel-5_112
Changes since 1.2:	+3 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			AE - simpler/faster/newer/cooler AnyEvent API
4
5			=head1 SYNOPSIS
6
7	root	1.2	use AnyEvent; # not AE
8	root	1.1
9			=head1 DESCRIPTION
10
11	root	1.2	This module documents the new simpler AnyEvent API.
12	root	1.1
13			The rationale for the new API is that experience with L<EV> shows that
14	root	1.3	this API actually "works", despite it's lack of extensibility, leading to
15			a shorter, easier and faster API.
16	root	1.1
17	root	1.2	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 noticable (with EV it increases the time five- to
27			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	root	1.3	no plans to "switch", so if in doubt, use the L<AnyEvent> API.
36	root	1.2
37			As the AE API is complementary, not everything in the AnyEvent API is
38			available, so you still need to use AnyEvent for the finer stuff. Also,
39			you should not C<use AE> directly, C<use AnyEvent> will provide the AE
40			namespace.
41
42			=head2 FUNCTIONS
43
44			This section briefly describes the alternative watcher
45			constructors. Semantics and any methods are not described here, please
46			refer to the L<AnyEvent> manpage for the details.
47
48			=over 4
49	root	1.1
50			=cut
51
52			package AE;
53
54			use AnyEvent (); # BEGIN { AnyEvent::common_sense }
55
56	root	1.2	=item $w = AE::io $fh_or_fd, $watch_write, $cb
57
58			Creates an I/O watcher that listens for read events (C<$watch_write>
59			false) or write events (C<$watch_write> is true) on the file handle or
60			file descriptor C<$fh_or_fd>.
61
62			The callback C<$cb> is invoked as soon and as long as I/O of the type
63			specified by C<$watch_write>) can be done on the file handle/descriptor.
64
65			Example: wait until STDIN becomes readable.
66
67			$stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> };
68
69			Example. wait until STDOUT becomes writable and print something.
70
71			$stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" };
72
73			=item $w = AE::timer $after, $interval, $cb
74
75			Creates a timer watcher that invokes the callback C<$cb> after at least
76			C<$after> second have passed (C<$after> can be negative or C<0>).
77
78			If C<$interval> is C<0>, then the clalback will only be invoked once,
79			otherwise it must be a positive number of seconds that specified the
80			interval between successive invocations of the callback.
81
82			Example: print "too late" after at least one second has passed.
83
84			$timer_once = AE::timer 1, 0, sub { print "too late\n" };
85
86			Example: print "blubb" once a second, starting as soon as possible.
87
88			$timer_repeated = AE::timer 0, 1, sub { print "blubb\n" };
89
90			=item $w = AE::signal $signame, $cb
91
92			Invoke the callback c<$cb> each time one or more occurences of the named
93			signal C<$signame> are detected.
94
95			=item $w = AE::child $pid, $cb
96
97			Invokes the callbakc C<$cb> when the child with the given C<$pid> exits
98			(or all children, when C<$pid> is zero).
99
100			The callback will get the actual pid and exit status as arguments.
101
102			=item $w = AE::idle $cb
103
104			Invoke the callback C<$cb> each time the event loop is "idle" (has no
105			events outstanding), but do not prevent the event loop from polling for
106			more events.
107
108			=item $cv = AE::cv
109
110			=item $cv = AE::cv { BLOCK }
111
112			Create a new condition variable. The first form is identical to C<<
113			AnyEvent->condvar >>, the second form additionally sets the callback (as
114			if the C<cb> method is called on the condition variable).
115
116			=item AE::now
117
118			Returns the current event loop time (may be cached by the event loop).
119
120			=item AE::now_update
121
122			Ensures that the current event loop time is up to date.
123
124			=item AE::time
125
126			Return the current time (not cached, always consults a hardware clock).
127
128			=back
129	root	1.1
130			=head1 AUTHOR
131
132			Marc Lehmann <schmorp@schmorp.de>
133			http://home.schmorp.de/
134
135			=cut
136
137	root	1.2	1
138