AnyEvent/lib/AE.pm

=head1 NAME

AE - simpler/faster/newer/cooler AnyEvent API

=head1 SYNOPSIS

  use AnyEvent; # not AE

  # file handle or descriptor readable
  my $w = AE::io $fh, 0, sub { ...  };

  # one-shot or repeating timers
  my $w = AE::timer $seconds,         0, sub { ... }; # once
  my $w = AE::timer $seconds, $interval, sub { ... }; # repeated

  print AE::now;  # prints current event loop time
  print AE::time; # think Time::HiRes::time or simply CORE::time.

  # POSIX signal
  my $w = AE::signal TERM => sub { ... };

  # child process exit
  my $w = AE::child $pid, sub {
     my ($pid, $status) = @_;
     ...
  };

  # called when event loop idle (if applicable)
  my $w = AE::idle sub { ... };

  my $cv = AE::cv; # stores whether a condition was flagged
  $cv->send; # wake up current and all future recv's
  $cv->recv; # enters "main loop" till $condvar gets ->send
  # use a condvar in callback mode:
  $cv->cb (sub { $_[0]->recv });


=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 its lack of extensibility, leading to
a shorter, easier and faster API.

The main differences from AnyEvent is that function calls are used
instead of method calls, 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 compile-time with this API.

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

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

As the AE API is complementary, not everything in the AnyEvent API is
available, and 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.

At the moment, these functions will become slower then their method-call
counterparts when using L<AnyEvent::Strict> or L<AnyEvent::Debug>::wrap.

=head2 FUNCTIONS

This section briefly describes the alternative watcher constructors and
other functions available inside the C<AE> namespace. Semantics are not
described here; please refer to the description of the function or method
with the same name in the L<AnyEvent> manpage for the details.

=over 4

=cut

package AE;

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

our $VERSION = $AnyEvent::VERSION;

=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.

If you want a mnemomic for the second argument: C<0> is standard I<input>,
for I<reading>, and C<1> is standard I<output>, for I<writing>.

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 callback will only be invoked once,
otherwise it must be a positive number of seconds that specifies 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 occurrences of the
named signal C<$signame> are detected.

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

Invokes the callback 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).

=item AE::postpone { BLOCK }

Exactly the same as C<AnyEvent:::postpone>.

=item AE::log $level, $msg[, @args]

Exactly the same as C<AnyEvent::log> (or C<AnyEvent::Log::log>).

=back

=head1 AUTHOR

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

=cut

1

Revision:	1.18
Committed:	Sun Jul 12 16:31:59 2020 UTC (3 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.17:	+1 -1 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	root	1.7	# file handle or descriptor readable
10			my $w = AE::io $fh, 0, sub { ... };
11
12			# one-shot or repeating timers
13	root	1.8	my $w = AE::timer $seconds, 0, sub { ... }; # once
14			my $w = AE::timer $seconds, $interval, sub { ... }; # repeated
15	root	1.7
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	root	1.9	my $w = AE::idle sub { ... };
30	root	1.7
31	root	1.14	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	root	1.7	# use a condvar in callback mode:
35	root	1.14	$cv->cb (sub { $_[0]->recv });
36	root	1.7
37
38	root	1.1	=head1 DESCRIPTION
39
40	root	1.2	This module documents the new simpler AnyEvent API.
41	root	1.1
42			The rationale for the new API is that experience with L<EV> shows that
43	root	1.8	this API actually "works", despite its lack of extensibility, leading to
44	root	1.3	a shorter, easier and faster API.
45	root	1.1
46	root	1.8	The main differences from AnyEvent is that function calls are used
47			instead of method calls, and that no named arguments are used.
48	root	1.2
49			This makes calls to watcher creation functions really short, which can
50	root	1.8	make a program more readable despite the lack of named parameters.
51	root	1.2	Function calls also allow more static type checking than method calls, so
52	root	1.8	many mistakes are caught at compile-time with this API.
53	root	1.2
54			Also, some backends (Perl and EV) are so fast that the method call
55	root	1.6	overhead is very noticeable (with EV it increases the execution time five-
56			to six-fold, with Perl the method call overhead is about a factor of two).
57	root	1.2
58			Note that the C<AE> API is an alternative to, not the future version of,
59	root	1.12	the AnyEvent API. Both APIs can be used interchangeably and there are
60	root	1.6	no plans to "switch", so if in doubt, feel free to use the L<AnyEvent>
61			API in new code.
62	root	1.2
63			As the AE API is complementary, not everything in the AnyEvent API is
64	root	1.8	available, and you still need to use AnyEvent for the finer stuff. Also,
65	root	1.2	you should not C<use AE> directly, C<use AnyEvent> will provide the AE
66			namespace.
67
68	root	1.12	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
71	root	1.2	=head2 FUNCTIONS
72
73	root	1.13	This section briefly describes the alternative watcher constructors and
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
76			with the same name in the L<AnyEvent> manpage for the details.
77	root	1.2
78			=over 4
79	root	1.1
80			=cut
81
82			package AE;
83
84			use AnyEvent (); # BEGIN { AnyEvent::common_sense }
85
86	root	1.4	our $VERSION = $AnyEvent::VERSION;
87
88	root	1.2	=item $w = AE::io $fh_or_fd, $watch_write, $cb
89
90			Creates an I/O watcher that listens for read events (C<$watch_write>
91			false) or write events (C<$watch_write> is true) on the file handle or
92			file descriptor C<$fh_or_fd>.
93
94			The callback C<$cb> is invoked as soon and as long as I/O of the type
95			specified by C<$watch_write>) can be done on the file handle/descriptor.
96
97	root	1.18	If you want a mnemomic for the second argument: C<0> is standard I<input>,
98	root	1.17	for I<reading>, and C<1> is standard I<output>, for I<writing>.
99
100	root	1.2	Example: wait until STDIN becomes readable.
101
102			$stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> };
103
104	root	1.8	Example: wait until STDOUT becomes writable and print something.
105	root	1.2
106			$stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" };
107
108			=item $w = AE::timer $after, $interval, $cb
109
110			Creates a timer watcher that invokes the callback C<$cb> after at least
111			C<$after> second have passed (C<$after> can be negative or C<0>).
112
113	root	1.8	If C<$interval> is C<0>, then the callback will only be invoked once,
114			otherwise it must be a positive number of seconds that specifies the
115	root	1.2	interval between successive invocations of the callback.
116
117			Example: print "too late" after at least one second has passed.
118
119			$timer_once = AE::timer 1, 0, sub { print "too late\n" };
120
121			Example: print "blubb" once a second, starting as soon as possible.
122
123			$timer_repeated = AE::timer 0, 1, sub { print "blubb\n" };
124
125			=item $w = AE::signal $signame, $cb
126
127	root	1.8	Invoke the callback C<$cb> each time one or more occurrences of the
128			named signal C<$signame> are detected.
129	root	1.2
130			=item $w = AE::child $pid, $cb
131
132	root	1.8	Invokes the callback C<$cb> when the child with the given C<$pid> exits
133	root	1.2	(or all children, when C<$pid> is zero).
134
135			The callback will get the actual pid and exit status as arguments.
136
137			=item $w = AE::idle $cb
138
139			Invoke the callback C<$cb> each time the event loop is "idle" (has no
140			events outstanding), but do not prevent the event loop from polling for
141			more events.
142
143			=item $cv = AE::cv
144
145			=item $cv = AE::cv { BLOCK }
146
147			Create a new condition variable. The first form is identical to C<<
148			AnyEvent->condvar >>, the second form additionally sets the callback (as
149			if the C<cb> method is called on the condition variable).
150
151			=item AE::now
152
153			Returns the current event loop time (may be cached by the event loop).
154
155			=item AE::now_update
156
157			Ensures that the current event loop time is up to date.
158
159			=item AE::time
160
161			Return the current time (not cached, always consults a hardware clock).
162
163	root	1.10	=item AE::postpone { BLOCK }
164
165			Exactly the same as C<AnyEvent:::postpone>.
166
167	root	1.11	=item AE::log $level, $msg[, @args]
168
169			Exactly the same as C<AnyEvent::log> (or C<AnyEvent::Log::log>).
170
171	root	1.2	=back
172	root	1.1
173			=head1 AUTHOR
174
175			Marc Lehmann <schmorp@schmorp.de>
176	root	1.16	http://anyevent.schmorp.de
177	root	1.1
178			=cut
179
180	root	1.2	1
181