1 |
root |
1.2 |
=head1 Introduction to AnyEvent |
2 |
root |
1.1 |
|
3 |
root |
1.2 |
This is a tutorial that will introduce you to the features of AnyEvent. |
4 |
root |
1.1 |
|
5 |
root |
1.2 |
The first part introduces the core AnyEvent module (after swamping you a |
6 |
|
|
bit in evangelism), which might already provide all you ever need. |
7 |
root |
1.1 |
|
8 |
root |
1.2 |
The second part focuses on network programming using sockets, for which |
9 |
|
|
AnyEvent offers a lot of support you can use. |
10 |
|
|
|
11 |
|
|
|
12 |
|
|
=head1 What is AnyEvent? |
13 |
|
|
|
14 |
|
|
Skip this section if you want to see code, now! |
15 |
|
|
|
16 |
|
|
AnyEvent is first of all just a framework to do event-based |
17 |
|
|
programming. Typically such frameworks are an all-or-nothing thing: If you |
18 |
|
|
use one such framework, you can't (easily, or even at all) use another in |
19 |
|
|
the same program. |
20 |
|
|
|
21 |
|
|
AnyEvent is different - it is a thin abstraction layer above all kinds |
22 |
|
|
of event loops. Its main purpose is to move the choice of the underlying |
23 |
|
|
framework (the event loop) from the module author to the program author |
24 |
|
|
using the module. |
25 |
|
|
|
26 |
|
|
That means you can write code that uses events to control what it |
27 |
|
|
does, without forcing other code in the same program to use the same |
28 |
|
|
underlying framework as you do - i.e. you can create a Perl module |
29 |
|
|
that is event-based using AnyEvent, and users of that module can still |
30 |
|
|
choose between using L<Gtk2>, L<Tk>, L<Event> or no event loop at |
31 |
|
|
all: AnyEvent comes with its own event loop implementation, so your |
32 |
|
|
code works regardless of other modules that might or might not be |
33 |
|
|
installed. The latter is important, as AnyEvent does not have any |
34 |
|
|
dependencies to other modules, which makes it easy to install, for |
35 |
|
|
example, when you lack a C compiler. |
36 |
|
|
|
37 |
|
|
A typical problem with Perl modules such as L<Net::IRC> is that they |
38 |
|
|
come with their own event loop: In L<Net::IRC>, the program who uses it |
39 |
|
|
needs to start the event loop of L<Net::IRC>. That means that one cannot |
40 |
|
|
integrate this module into a L<Gtk2> GUI for instance, as that module, |
41 |
|
|
too, enforces the use of its own event loop (namely L<Glib>). |
42 |
root |
1.1 |
|
43 |
|
|
Another example is L<LWP>: it provides no event interface at all. It's a |
44 |
|
|
pure blocking HTTP (and FTP etc.) client library, which usually means that |
45 |
|
|
you either have to start a thread or have to fork for a HTTP request, or |
46 |
|
|
use L<Coro::LWP>, if you want to do something else while waiting for the |
47 |
|
|
request to finish. |
48 |
|
|
|
49 |
|
|
The motivation behind these designs is often that a module doesn't want to |
50 |
|
|
depend on some complicated XS-module (Net::IRC), or that it doesn't want |
51 |
root |
1.2 |
to force the user to use some specific event loop at all (LWP). |
52 |
root |
1.1 |
|
53 |
root |
1.2 |
L<AnyEvent> solves this dilemma, by B<not> forcing module authors to either |
54 |
root |
1.1 |
|
55 |
|
|
=over 4 |
56 |
|
|
|
57 |
root |
1.2 |
=item write their own event loop (because guarantees to offer one |
58 |
|
|
everywhere - even on windows). |
59 |
root |
1.1 |
|
60 |
root |
1.2 |
=item choose one fixed event loop (because AnyEvent works with all |
61 |
|
|
important event loops available for Perl, and adding others is trivial). |
62 |
root |
1.1 |
|
63 |
|
|
=back |
64 |
|
|
|
65 |
root |
1.2 |
If the module author uses L<AnyEvent> for all his event needs (IO events, |
66 |
|
|
timers, signals, ...) then all other modules can just use his module and |
67 |
|
|
don't have to choose an event loop or adapt to his event loop. The choice |
68 |
|
|
of the event loop is ultimately made by the program author who uses all |
69 |
|
|
the modules and writes the main program. And even there he doesn't have to |
70 |
|
|
choose, he can just let L<AnyEvent> choose the best available event loop |
71 |
|
|
for him. |
72 |
root |
1.1 |
|
73 |
|
|
Read more about this in the main documentation of the L<AnyEvent> module. |
74 |
|
|
|
75 |
|
|
|
76 |
root |
1.2 |
=head1 Introduction to Event-Based Programming |
77 |
|
|
|
78 |
|
|
So what exactly is programming using events? It quite simply means that |
79 |
|
|
instead of your code actively waiting for something, such as the user |
80 |
|
|
entering something on STDIN: |
81 |
|
|
|
82 |
|
|
$| = 1; print "enter your name> "; |
83 |
|
|
|
84 |
|
|
my $name = <STDIN>; |
85 |
|
|
|
86 |
|
|
You instead tell your event framework to notify you in the event of some |
87 |
|
|
data being available on STDIN, by using a callback mechanism: |
88 |
|
|
|
89 |
|
|
use AnyEvent; |
90 |
|
|
|
91 |
|
|
$| = 1; print "enter your name> "; |
92 |
|
|
|
93 |
|
|
my $name; |
94 |
|
|
|
95 |
|
|
my $wait_for_input = AnyEvent->io ( |
96 |
|
|
fh => \*STDIN, # which file handle to check |
97 |
|
|
poll => "r", # which event to wait for ("r"ead data) |
98 |
|
|
cb => sub { # what callback to execute |
99 |
|
|
$name = <STDIN>; # read it |
100 |
|
|
} |
101 |
|
|
); |
102 |
|
|
|
103 |
|
|
# do something else here |
104 |
|
|
|
105 |
|
|
Looks more complicated, and surely is, but the advantage of using events |
106 |
|
|
is that your program can do something else instead of waiting for |
107 |
|
|
input. Waiting as in the first example is also called "blocking" because |
108 |
|
|
you "block" your process from executing anything else while you do so. |
109 |
|
|
|
110 |
|
|
The second example avoids blocking, by only registering interest in a read |
111 |
|
|
event, which is fast and doesn't block your process. Only when read data |
112 |
|
|
is available will the callback be called, which can then proceed to read |
113 |
|
|
the data. |
114 |
|
|
|
115 |
|
|
The "interest" is represented by an object returned by C<< AnyEvent->io |
116 |
|
|
>> called a "watcher" object - called like that because it "watches" your |
117 |
|
|
file handle (or other event sources) for the event you are interested in. |
118 |
|
|
|
119 |
|
|
In the example above, we create an I/O watcher by calling the C<< |
120 |
|
|
AnyEvent->io >> method. Disinterest in some event is simply expressed by |
121 |
|
|
forgetting about the watcher, for example, by C<undef>'ing the variable it |
122 |
|
|
is stored in. AnyEvent will automatically clean up the watcher if it is no |
123 |
|
|
longer used, much like Perl closes your file handles if you no longer use |
124 |
|
|
them anywhere. |
125 |
|
|
|
126 |
|
|
=head2 Condition Variables |
127 |
|
|
|
128 |
|
|
However, the above is not a fullly working program, and will not work |
129 |
|
|
as-is. The reason is that your callback will not be invoked out of the |
130 |
|
|
blue, you have to run the event loop. Also, event-based programs sometimes |
131 |
|
|
have to block, too, as when there simply is nothing else to do and |
132 |
|
|
everything waits for some events, it needs to block the process as well. |
133 |
|
|
|
134 |
|
|
In AnyEvent, this is done using condition variables. Condition variables |
135 |
|
|
are named "condition variables" because they represent a condition that is |
136 |
|
|
initially false and needs to be fulfilled. |
137 |
|
|
|
138 |
|
|
You can also call them mergepoints, syncpoints, rendezvous ports or even |
139 |
|
|
callbacks and many other things (and they are often called like this in |
140 |
|
|
other frameworks). The important point is that you can create them freely |
141 |
|
|
and later wait for them to become true. |
142 |
|
|
|
143 |
|
|
Condition variables have two sides - one side is the "producer" of the |
144 |
|
|
condition (whatever code detects the condition), the other side is the |
145 |
|
|
"consumer" (the code that waits for that condition). |
146 |
|
|
|
147 |
|
|
In our example in the previous section, the producer is the event callback |
148 |
|
|
and there is no consumer yet - let's change that now: |
149 |
|
|
|
150 |
|
|
use AnyEvent; |
151 |
|
|
|
152 |
|
|
$| = 1; print "enter your name> "; |
153 |
|
|
|
154 |
|
|
my $name; |
155 |
|
|
|
156 |
|
|
my $name_ready = AnyEvent->condvar; |
157 |
|
|
|
158 |
|
|
my $wait_for_input = AnyEvent->io ( |
159 |
|
|
fh => \*STDIN, |
160 |
|
|
poll => "r", |
161 |
|
|
cb => sub { |
162 |
|
|
$name = <STDIN>; |
163 |
|
|
$name_ready->send; |
164 |
|
|
} |
165 |
|
|
); |
166 |
|
|
|
167 |
|
|
# do something else here |
168 |
|
|
|
169 |
|
|
# now wait until the name is available: |
170 |
|
|
$name_ready->recv; |
171 |
|
|
|
172 |
|
|
undef $wait_for_input; # watche rno longer needed |
173 |
|
|
|
174 |
|
|
print "your name is $name\n"; |
175 |
|
|
|
176 |
|
|
This program creates an AnyEvent condvar by calling the C<< |
177 |
|
|
AnyEvent->condvar >> method. It then creates a watcher as usual, but |
178 |
|
|
inside the callback it C<send>'s the C<$name_ready> condition variable, |
179 |
|
|
which causes anybody waiting on it to continue. |
180 |
|
|
|
181 |
|
|
The "anybody" in this case is the code that follows, which calls C<< |
182 |
|
|
$name_ready->recv >>: The producer calls C<send>, the consumer calls |
183 |
|
|
C<recv>. |
184 |
|
|
|
185 |
|
|
If there is no C<$name> available yet, then the call to C<< |
186 |
|
|
$name_ready->recv >> will halt your program until the condition becomes |
187 |
|
|
true. |
188 |
|
|
|
189 |
|
|
As the names C<send> and C<recv> imply, you can actually send and receive |
190 |
|
|
data using this, for example, the above code could also be written like |
191 |
|
|
this, without an extra variable to store the name in: |
192 |
|
|
|
193 |
|
|
use AnyEvent; |
194 |
|
|
|
195 |
|
|
$| = 1; print "enter your name> "; |
196 |
|
|
|
197 |
|
|
my $name_ready = AnyEvent->condvar; |
198 |
|
|
|
199 |
|
|
my $wait_for_input = AnyEvent->io ( |
200 |
|
|
fh => \*STDIN, poll => "r", |
201 |
|
|
cb => sub { $name_ready->send (scalar = <STDIN>) } |
202 |
|
|
); |
203 |
|
|
|
204 |
|
|
# do something else here |
205 |
|
|
|
206 |
|
|
# now wait and fetch the name |
207 |
|
|
my $name = $name_ready->recv; |
208 |
|
|
|
209 |
|
|
undef $wait_for_input; # watche rno longer needed |
210 |
|
|
|
211 |
|
|
print "your name is $name\n"; |
212 |
|
|
|
213 |
|
|
You can pass any number of arguments to C<send>, and everybody call to |
214 |
|
|
C<recv> will return them. |
215 |
|
|
|
216 |
|
|
=head2 The "main loop" |
217 |
|
|
|
218 |
|
|
Most event-based frameworks have something called a "main loop" or "event |
219 |
|
|
loop run function" or something similar. |
220 |
|
|
|
221 |
|
|
Just like in C<recv> AnyEvent, these functions need to be called |
222 |
|
|
eventually so that your event loop has a chance of actually looking for |
223 |
|
|
those events you are interested in. |
224 |
|
|
|
225 |
|
|
For example, in a L<Gtk2> program, the above example could also be written |
226 |
|
|
like this: |
227 |
|
|
|
228 |
|
|
use Gtk2 -init; |
229 |
|
|
use AnyEvent; |
230 |
|
|
|
231 |
|
|
############################################ |
232 |
|
|
# create a window and some label |
233 |
|
|
|
234 |
|
|
my $window = new Gtk2::Window "toplevel"; |
235 |
|
|
$window->add (my $label = new Gtk2::Label "soon replaced by name"); |
236 |
|
|
|
237 |
|
|
$window->show_all; |
238 |
|
|
|
239 |
|
|
############################################ |
240 |
|
|
# do our AnyEvent stuff |
241 |
|
|
|
242 |
|
|
$| = 1; print "enter your name> "; |
243 |
|
|
|
244 |
|
|
my $name_ready = AnyEvent->condvar; |
245 |
|
|
|
246 |
|
|
my $wait_for_input = AnyEvent->io ( |
247 |
|
|
fh => \*STDIN, poll => "r", |
248 |
|
|
cb => sub { |
249 |
|
|
# set the label |
250 |
|
|
$label->set_text (scalar <STDIN>); |
251 |
|
|
print "enter another name> "; |
252 |
|
|
} |
253 |
|
|
); |
254 |
|
|
|
255 |
|
|
############################################ |
256 |
|
|
# Now enter Gtk2's event loop |
257 |
|
|
|
258 |
|
|
main Gtk2; |
259 |
|
|
|
260 |
|
|
No condition variable anywhere in sight - instead, we just read a line |
261 |
|
|
from STDIN and replace the text in the label. In fact, since nobody |
262 |
|
|
C<undef>'s C<$wait_for_input> you can enter multiple lines. |
263 |
|
|
|
264 |
|
|
Instead of waiting for a condition variable, the program enters the Gtk2 |
265 |
|
|
main loop by calling C<< Gtk2->main >>, which will block the program and |
266 |
|
|
wait for events to arrive. |
267 |
|
|
|
268 |
|
|
This also shows that AnyEvent is quite flexible - you didn't have anything |
269 |
|
|
to do to make the AnyEvent watcher use Gtk2 (actually Glib) - it just |
270 |
|
|
worked. |
271 |
|
|
|
272 |
|
|
Admittedly, the example is a bit silly - who would want to read names |
273 |
|
|
form standard input in a Gtk+ application. But imagine that instead of |
274 |
|
|
doing that, you would make a HTTP request in the background and display |
275 |
|
|
it's results. In fact, with event-based programming you can make many |
276 |
|
|
http-requests in parallel in your program and still provide feedback to |
277 |
|
|
the user and stay interactive. |
278 |
|
|
|
279 |
|
|
In the next part you will see how to do just that - by implementing an |
280 |
|
|
HTTP request, on our own, with the utility modules AnyEvent comes with. |
281 |
|
|
|
282 |
root |
1.4 |
Before that, however, let's briefly look at how you would write your |
283 |
root |
1.2 |
program with using only AnyEvent, without ever calling some other event |
284 |
|
|
loop's run function. |
285 |
|
|
|
286 |
|
|
In the example using condition variables, we used that, and in fact, this |
287 |
|
|
is the solution: |
288 |
|
|
|
289 |
|
|
my $quit_program = AnyEvent->condvar; |
290 |
|
|
|
291 |
|
|
# create AnyEvent watchers (or not) here |
292 |
|
|
|
293 |
|
|
$quit_program->recv; |
294 |
|
|
|
295 |
|
|
If any of your watcher callbacks decide to quit, they can simply call |
296 |
|
|
C<< $quit_program->send >>. Of course, they could also decide not to and |
297 |
|
|
simply call C<exit> instead, or they could decide not to quit, ever (e.g. |
298 |
|
|
in a long-running daemon program). |
299 |
|
|
|
300 |
|
|
In that case, you can simply use: |
301 |
|
|
|
302 |
|
|
AnyEvent->condvar->recv; |
303 |
|
|
|
304 |
|
|
And this is, in fact, closest to the idea of a main loop run function that |
305 |
|
|
AnyEvent offers. |
306 |
|
|
|
307 |
|
|
=head2 Timers and other event sources |
308 |
|
|
|
309 |
|
|
So far, we have only used I/O watchers. These are useful mainly to find |
310 |
|
|
out wether a Socket has data to read, or space to write more data. On sane |
311 |
|
|
operating systems this also works for console windows/terminals (typically |
312 |
|
|
on standard input), serial lines, all sorts of other devices, basically |
313 |
|
|
almost everything that has a file descriptor but isn't a file itself. (As |
314 |
|
|
usual, "sane" excludes windows - on that platform you would need different |
315 |
|
|
functions for all of these, complicating code immesely - think "socket |
316 |
|
|
only" on windows). |
317 |
|
|
|
318 |
|
|
However, I/O is not everything - the secondmost important event source is |
319 |
|
|
the clock. For example when doing an HTTP request you might want to time |
320 |
|
|
out when the server doesn't answre within some predefined amount of time. |
321 |
|
|
|
322 |
|
|
In AnyEvent, timer event watchers are created by calling the C<< |
323 |
|
|
AnyEvent->timer >> method: |
324 |
|
|
|
325 |
|
|
use AnyEvent; |
326 |
|
|
|
327 |
|
|
my $cv = AnyEvent->condvar; |
328 |
|
|
|
329 |
|
|
my $wait_one_and_a_half_seconds = AnyEvent->timer ( |
330 |
|
|
after => 1.5, # after how many seconds to invoke the cb? |
331 |
|
|
cb => sub { # the callback to invoke |
332 |
|
|
$cv->send; |
333 |
|
|
}, |
334 |
|
|
); |
335 |
|
|
|
336 |
|
|
# can do somehting else here |
337 |
|
|
|
338 |
|
|
# now wait till our time has come |
339 |
|
|
$cv->recv; |
340 |
|
|
|
341 |
|
|
Unlike I/O watchers, timers are only interested in the amount of seconds |
342 |
|
|
they have to wait. When that amount of time has passed, AnyEvent will |
343 |
|
|
invoke your callback. |
344 |
|
|
|
345 |
|
|
Unlike I/O watchers, which will call your callback as many times as there |
346 |
|
|
is data available, timers are one-shot: after they have "fired" once and |
347 |
|
|
invoked your callback, they are dead and no longer do anything. |
348 |
|
|
|
349 |
|
|
To get a repeating timer, such as a timer firing roughly once per second, |
350 |
|
|
you have to recreate it: |
351 |
|
|
|
352 |
|
|
use AnyEvent; |
353 |
|
|
|
354 |
|
|
my $time_watcher; |
355 |
|
|
|
356 |
|
|
sub once_per_second { |
357 |
|
|
print "tick\n"; |
358 |
|
|
|
359 |
|
|
# (re-)create the watcher |
360 |
|
|
$time_watcher = AnyEvent->timer ( |
361 |
|
|
after => 1, |
362 |
|
|
cb => \&once_per_second, |
363 |
|
|
); |
364 |
|
|
} |
365 |
|
|
|
366 |
|
|
# now start the timer |
367 |
|
|
once_per_second; |
368 |
|
|
|
369 |
|
|
Having to recreate your timer is a restriction put on AnyEvent that is |
370 |
|
|
present in most event libraries it uses. It is so annoying that some |
371 |
|
|
future version might worka round this limitation, but right now, it's the |
372 |
|
|
only way to do repeating timers. |
373 |
|
|
|
374 |
|
|
Fortunately most timers aren't really repeating but specify timeouts of |
375 |
|
|
some sort. |
376 |
|
|
|
377 |
|
|
=head3 More esoteric sources |
378 |
|
|
|
379 |
|
|
AnyEvent also has some other, more esoteric event sources you can tap |
380 |
|
|
into: signal and child watchers. |
381 |
|
|
|
382 |
|
|
Signal watchers can be used to wait for "signal events", which simply |
383 |
|
|
means your process got send a signal (Such as C<SIGTERM> or C<SIGUSR1>). |
384 |
|
|
|
385 |
|
|
Process watchers wait for a child process to exit. They are useful when |
386 |
|
|
you fork a separate process and ened to know when it exits, but you do not |
387 |
|
|
wait for that by blocking. |
388 |
|
|
|
389 |
|
|
Both watcher types are described in detail in the main L<AnyEvent> manual |
390 |
|
|
page. |
391 |
|
|
|
392 |
|
|
|
393 |
|
|
=head1 Network programming and AnyEvent |
394 |
|
|
|
395 |
root |
1.3 |
So far you have seen how to register event watchers and handle events. |
396 |
root |
1.1 |
|
397 |
root |
1.3 |
This is a great basis to write network clients and servers, and might be |
398 |
|
|
all that your module (or program) ever requires, but writing your own I/O |
399 |
|
|
buffering again and again becomes tedious, not to mention that it attracts |
400 |
|
|
errors. |
401 |
|
|
|
402 |
|
|
While the core L<AnyEvent> module is still small and self-contained, |
403 |
|
|
the distribution comes with some very useful utility modules such as |
404 |
|
|
L<AnyEvent::Handle>, L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can |
405 |
|
|
make your life as non-blocking network programmer a lot easier. |
406 |
|
|
|
407 |
root |
1.4 |
Here is a quick overview over these three modules: |
408 |
|
|
|
409 |
|
|
=head2 L<AnyEvent::DNS> |
410 |
|
|
|
411 |
|
|
This module allows fully asynchronous DNS resolution. It is used mainly by |
412 |
|
|
L<AnyEvent::Socket> to resolve hostnames and service ports for you, but is |
413 |
|
|
a great way to do other DNS resolution tasks, such as reverse lookups of |
414 |
|
|
IP addresses for log files. |
415 |
root |
1.1 |
|
416 |
root |
1.2 |
=head2 L<AnyEvent::Handle> |
417 |
root |
1.1 |
|
418 |
|
|
This module handles non-blocking IO on file handles in an event based |
419 |
|
|
manner. It provides a wrapper object around your file handle that provides |
420 |
|
|
queueing and buffering of incoming and outgoing data for you. |
421 |
|
|
|
422 |
root |
1.4 |
It also implements the most common data formats, such as text lines, or |
423 |
|
|
fixed and variable-width data blocks. |
424 |
root |
1.1 |
|
425 |
root |
1.2 |
=head2 L<AnyEvent::Socket> |
426 |
root |
1.1 |
|
427 |
|
|
This module provides you with functions that handle socket creation |
428 |
|
|
and IP address magic. The two main functions are C<tcp_connect> and |
429 |
|
|
C<tcp_server>. The former will connect a (streaming) socket to an internet |
430 |
|
|
host for you and the later will make a server socket for you, to accept |
431 |
|
|
connections. |
432 |
|
|
|
433 |
|
|
This module also comes with transparent IPv6 support, this means: If you |
434 |
|
|
write your programs with this module, you will be IPv6 ready without doing |
435 |
root |
1.4 |
anything special. |
436 |
root |
1.1 |
|
437 |
|
|
It also works around a lot of portability quirks (especially on the |
438 |
|
|
windows platform), which makes it even easier to write your programs in a |
439 |
root |
1.4 |
portable way (did you know that windows uses different error codes for all |
440 |
|
|
socket functions and that Perl does not know about these? That "Unknown |
441 |
|
|
error 10022" (which is C<WSAEINVAL>) can mean that our C<connect> call was |
442 |
|
|
successful? That unsuccessful TCP connects might never be reported back |
443 |
|
|
to your program? That C<WSAEINPROGRESS> means your C<connect> call was |
444 |
|
|
ignored instead of being in progress? AnyEvent::Socket works around all of |
445 |
|
|
these Windows/Perl bugs for you). |
446 |
|
|
|
447 |
|
|
=head2 First experiments with non-blocking connects: a parallel finger |
448 |
|
|
client. |
449 |
|
|
|
450 |
|
|
The finger protocol is one of the simplest protocols in use on the |
451 |
|
|
internet. Or in use in the past, as almost nobody uses it anymore. |
452 |
|
|
|
453 |
|
|
It works by connecting to the finger port on another host, writing a |
454 |
|
|
single line with a user name and then reading the finger response, as |
455 |
|
|
specified by that user. OK, RFC 1288 specifies a vastly more complex |
456 |
|
|
protocol, but it basically boils down to this: |
457 |
|
|
|
458 |
|
|
# telnet idsoftware.com finger |
459 |
|
|
Trying 192.246.40.37... |
460 |
|
|
Connected to idsoftware.com (192.246.40.37). |
461 |
|
|
Escape character is '^]'. |
462 |
|
|
johnc |
463 |
|
|
Welcome to id Software's Finger Service V1.5! |
464 |
|
|
|
465 |
|
|
[...] |
466 |
|
|
Now on the web: |
467 |
|
|
[...] |
468 |
|
|
|
469 |
|
|
Connection closed by foreign host. |
470 |
|
|
|
471 |
|
|
Yeah, I<was> used indeed, but at least the finger daemon still works, so |
472 |
|
|
let's write a little AnyEvent function that makes a finger request: |
473 |
|
|
|
474 |
|
|
use AnyEvent; |
475 |
|
|
use AnyEvent::Socket; |
476 |
|
|
|
477 |
|
|
sub finger($$) { |
478 |
|
|
my ($user, $host) = @_; |
479 |
|
|
|
480 |
|
|
# use a condvar to return results |
481 |
|
|
my $cv = AnyEvent->condvar; |
482 |
|
|
|
483 |
|
|
# first, connect to the host |
484 |
|
|
tcp_connect $host, "finger", sub { |
485 |
|
|
# the callback gets the socket handle - or nothing |
486 |
|
|
my ($fh) = @_ |
487 |
|
|
or return $cv->send; |
488 |
|
|
|
489 |
|
|
# now write the username |
490 |
|
|
syswrite $fh, "$user\015\012"; |
491 |
|
|
|
492 |
|
|
my $response; |
493 |
|
|
|
494 |
|
|
# register a read watcher |
495 |
|
|
my $read_watcher; $read_watcher = AnyEvent->io ( |
496 |
|
|
fh => $fh, |
497 |
|
|
poll => "r", |
498 |
|
|
cb => sub { |
499 |
|
|
my $len = sysread $fh, $response, 1024, length $response; |
500 |
|
|
|
501 |
|
|
if ($len <= 0) { |
502 |
|
|
# we are done, or an error occured, lets ignore the latter |
503 |
|
|
undef $read_watcher; # no longer interested |
504 |
|
|
$cv->send ($response); # send results |
505 |
|
|
} |
506 |
|
|
}, |
507 |
|
|
); |
508 |
|
|
}; |
509 |
|
|
|
510 |
|
|
# pass $cv to the caller |
511 |
|
|
$cv |
512 |
|
|
} |
513 |
|
|
|
514 |
|
|
That's a mouthful! Let's dissect this function a bit, first the overall function: |
515 |
|
|
|
516 |
|
|
sub finger($$) { |
517 |
|
|
my ($user, $host) = @_; |
518 |
|
|
|
519 |
|
|
# use a condvar to return results |
520 |
|
|
my $cv = AnyEvent->condvar; |
521 |
|
|
|
522 |
|
|
# first, connect to the host |
523 |
|
|
tcp_connect $host, "finger", sub { |
524 |
|
|
... |
525 |
|
|
}; |
526 |
|
|
|
527 |
|
|
$cv |
528 |
|
|
} |
529 |
|
|
|
530 |
|
|
This isn't too complicated, just a function with two parameters, which |
531 |
|
|
creates a condition variable, returns it, and while it does that, |
532 |
|
|
initiates a TCP connect to the passed C<$host>. The condition variable |
533 |
|
|
will be used by the caller to receive the finger response. |
534 |
|
|
|
535 |
|
|
Since we are event-based programmers, we do not wait for the connect to |
536 |
|
|
finish - it could block your program for a minute or longer! |
537 |
|
|
|
538 |
|
|
Instead, we pass C<tcp_connect> the callback it should invoke when the |
539 |
|
|
connect is done. If it is successful, our callback gets passed the socket |
540 |
|
|
handle as first argument, otherwise, nothing will be passed. |
541 |
|
|
|
542 |
|
|
Let's look at our callback in more detail: |
543 |
|
|
|
544 |
|
|
# the callback gets the socket handle - or nothing |
545 |
|
|
my ($fh) = @_ |
546 |
|
|
or return $cv->send; |
547 |
|
|
|
548 |
|
|
The first thing the callback does is indeed save the passed socket handle |
549 |
|
|
in C<$fh>. When there was an error (no arguments), then our instinct would |
550 |
|
|
tell us to die: |
551 |
|
|
|
552 |
|
|
my ($fh) = @_ |
553 |
|
|
or die "$host: $!"; |
554 |
root |
1.1 |
|
555 |
root |
1.4 |
While this would give good feedback to the user, our program would |
556 |
|
|
probably freeze here, as we never report the results to anybody, certainly |
557 |
|
|
not the caller of our C<finger> function! |
558 |
|
|
|
559 |
|
|
This is why we instead return, but also call C<< $cv->send >> without any |
560 |
|
|
arguments to signal to our consumer that something bad has happened. The |
561 |
|
|
return value of C<< $cv->send >> is irrelevant, as is the return value of |
562 |
|
|
our callback. The return statement is simply used for the side effect of, |
563 |
|
|
well, returning immediately from the callback. |
564 |
|
|
|
565 |
|
|
As the next step in the finger protocol, we send the username to the |
566 |
|
|
finger daemon on the other side of our connection: |
567 |
|
|
|
568 |
|
|
syswrite $fh, "$user\015\012"; |
569 |
|
|
|
570 |
|
|
Note that this isn't 100% clean - the socket could, for whatever reasons, |
571 |
|
|
not accept our data. When writing a small amount of data like in this |
572 |
|
|
example it doesn't matter, but for real-world cases you might need to |
573 |
|
|
implement some kind of write buffering - or use L<AnyEvent::Handle>, which |
574 |
|
|
handles these matters for you. |
575 |
|
|
|
576 |
|
|
What we do have to do is to implement our own read buffer - the response |
577 |
|
|
data could arrive late or in multiple chunks, and we cannot just wait for |
578 |
|
|
it (event-based programming, you know?). |
579 |
|
|
|
580 |
|
|
To do that, we register a read watcher on the socket which waits for data: |
581 |
|
|
|
582 |
|
|
my $read_watcher; $read_watcher = AnyEvent->io ( |
583 |
|
|
fh => $fh, |
584 |
|
|
poll => "r", |
585 |
|
|
|
586 |
|
|
There is a trick here, however: the read watcher isn't stored in a global |
587 |
|
|
variable, but in a local one - if the callback returns, it would normally |
588 |
|
|
destroy the variable and its contents, which would in turn unregister our |
589 |
|
|
watcher again. |
590 |
|
|
|
591 |
|
|
To avoid that, we C<undef>ine the variable in the watcher callback. This |
592 |
|
|
means that, when the C<tcp_connect> callback returns, that Perl thinks |
593 |
|
|
(quite correctly) that the read watcher is still in use - namely in the |
594 |
|
|
callback. |
595 |
|
|
|
596 |
|
|
The callback itself calls C<sysread> for as many times as necessary, until |
597 |
|
|
C<sysread> returns an error or end-of-file: |
598 |
|
|
|
599 |
|
|
cb => sub { |
600 |
|
|
my $len = sysread $fh, $response, 1024, length $response; |
601 |
|
|
|
602 |
|
|
if ($len <= 0) { |
603 |
|
|
|
604 |
|
|
Note that C<sysread> has the ability to append data it reads to a scalar, |
605 |
|
|
which is what we make good use of in this example. |
606 |
|
|
|
607 |
|
|
When C<sysread> indicates we are done, the callback C<undef>ines |
608 |
|
|
the watcher and then C<send>'s the response data to the condition |
609 |
|
|
variable. All this has the following effects: |
610 |
|
|
|
611 |
|
|
Undefining the watcher destroys it, as our callback was the only one still |
612 |
|
|
having a reference to it. When the watcher gets destroyed, it destroys the |
613 |
|
|
callback, which in turn means the C<$fh> handle is no longer used, so that |
614 |
|
|
gets destroyed as well. The result is that all resources will be nicely |
615 |
|
|
cleaned up by perl for us. |
616 |
|
|
|
617 |
|
|
=head3 Using the finger client |
618 |
|
|
|
619 |
|
|
Now, we could probably write the same finger client simpler if we used |
620 |
|
|
C<IO::Socket::INET>, ignored the problem of multiple hosts and ignored |
621 |
|
|
IPv6 and a few other things. |
622 |
|
|
|
623 |
|
|
But the main advantage is that we can not only run this finger function in |
624 |
|
|
the background, we even can run multiple sessions in parallel, like this: |
625 |
|
|
|
626 |
|
|
my $f1 = finger "trouble", "noc.dfn.de"; # check for trouble tickets |
627 |
|
|
my $f2 = finger "1736" , "noc.dfn.de"; # fetch ticket 1736 |
628 |
|
|
my $f3 = finger "johnc", "idsoftware.com"; # finger john |
629 |
|
|
|
630 |
|
|
print "trouble tickets:\n", $f1->recv, "\n"; |
631 |
|
|
print "trouble ticket #1736:\n", $f2->recv, "\n"; |
632 |
|
|
print "john carmacks finger file: ", $f3->recv, "\n"; |
633 |
|
|
|
634 |
|
|
It doesn't look like it, but in fact all three requests run in |
635 |
|
|
parallel. The code waits for the first finger request to finish first, but |
636 |
|
|
that doesn't keep it from executing all three in parallel. |
637 |
|
|
|
638 |
|
|
=head3 Criticism and fix |
639 |
|
|
|
640 |
|
|
To make this example more real-world-ready, we would not only implement |
641 |
|
|
some write buffering (for the paranoid), but we would also have to handle |
642 |
|
|
timeouts and maybe protocol errors. |
643 |
|
|
|
644 |
|
|
This quickly gets unwieldy, which is why we introduce L<AnyEvent::Handle> |
645 |
|
|
in the next section, which takes care of all these details for us. |
646 |
root |
1.1 |
|
647 |
|
|
|
648 |
|
|
=head2 First experiments with AnyEvent::Handle |
649 |
|
|
|
650 |
|
|
Now let's start with something simple: a program that reads from standard |
651 |
|
|
input in a non-blocking way, that is, in a way that lets your program do |
652 |
|
|
other things while it is waiting for input. |
653 |
|
|
|
654 |
|
|
First, the full program listing: |
655 |
|
|
|
656 |
|
|
#!/usr/bin/perl |
657 |
|
|
|
658 |
|
|
use AnyEvent; |
659 |
|
|
use AnyEvent::Handle; |
660 |
|
|
|
661 |
|
|
my $end_prog = AnyEvent->condvar; |
662 |
|
|
|
663 |
|
|
my $handle = |
664 |
|
|
AnyEvent::Handle->new ( |
665 |
|
|
fh => \*STDIN, |
666 |
|
|
on_eof => sub { |
667 |
|
|
print "received EOF, exiting...\n"; |
668 |
|
|
$end_prog->broadcast; |
669 |
|
|
}, |
670 |
|
|
on_error => sub { |
671 |
|
|
print "error while reading from STDIN: $!\n"; |
672 |
|
|
$end_prog->broadcast; |
673 |
|
|
} |
674 |
|
|
); |
675 |
|
|
|
676 |
|
|
$handle->push_read (sub { |
677 |
|
|
my ($handle) = @_; |
678 |
|
|
|
679 |
|
|
if ($handle->rbuf =~ s/^.*?\bend\b.*$//s) { |
680 |
|
|
print "got 'end', existing...\n"; |
681 |
|
|
$end_prog->broadcast; |
682 |
|
|
return 1 |
683 |
|
|
} |
684 |
|
|
|
685 |
|
|
0 |
686 |
|
|
}); |
687 |
|
|
|
688 |
|
|
$end_prog->recv; |
689 |
|
|
|
690 |
root |
1.4 |
That's a mouthful, so let's go through it step by step: |
691 |
root |
1.1 |
|
692 |
|
|
#!/usr/bin/perl |
693 |
|
|
|
694 |
|
|
use AnyEvent; |
695 |
|
|
use AnyEvent::Handle; |
696 |
|
|
|
697 |
|
|
Nothing unexpected here, just load AnyEvent for the event functionality |
698 |
|
|
and AnyEvent::Handle for your file handling needs. |
699 |
|
|
|
700 |
|
|
my $end_prog = AnyEvent->condvar; |
701 |
|
|
|
702 |
|
|
Here the program creates a so-called 'condition variable': Condition |
703 |
|
|
variables are a great way to signal the completion of some event, or to |
704 |
|
|
state that some condition became true (thus the name). |
705 |
|
|
|
706 |
|
|
This condition variable represents the condition that the program wants to |
707 |
|
|
terminate. Later in the progra, we will 'recv' that condition (call the |
708 |
|
|
C<recv> method on it), which will wait until the condition gets signalled |
709 |
|
|
(which is done by calling the C<send> method on it). |
710 |
|
|
|
711 |
|
|
The next step is to create the handle object: |
712 |
|
|
|
713 |
|
|
my $handle = |
714 |
|
|
AnyEvent::Handle->new ( |
715 |
|
|
fh => \*STDIN, |
716 |
|
|
on_eof => sub { |
717 |
|
|
print "received EOF, exiting...\n"; |
718 |
|
|
$end_prog->broadcast; |
719 |
|
|
}, |
720 |
|
|
|
721 |
|
|
This handle object will read from standard input. Setting the C<on_eof> |
722 |
|
|
callback should be done for every file handle, as that is a condition that |
723 |
|
|
we always need to check for when working with file handles, to prevent |
724 |
|
|
reading or writing to a closed file handle, or getting stuck indefinitely |
725 |
|
|
in case of an error. |
726 |
|
|
|
727 |
|
|
Speaking of errors: |
728 |
|
|
|
729 |
|
|
on_error => sub { |
730 |
|
|
print "error while reading from STDIN: $!\n"; |
731 |
|
|
$end_prog->broadcast; |
732 |
|
|
} |
733 |
|
|
); |
734 |
|
|
|
735 |
|
|
The C<on_error> callback is also not required, but we set it here in case |
736 |
|
|
any error happens when we read from the file handle. It is usually a good |
737 |
|
|
idea to set this callback and at least print some diagnostic message: Even |
738 |
|
|
in our small example an error can happen. More on this later... |
739 |
|
|
|
740 |
|
|
$handle->push_read (sub { |
741 |
|
|
|
742 |
|
|
Next we push a general read callback on the read queue, which |
743 |
|
|
will wait until we have received all the data we wanted to |
744 |
|
|
receive. L<AnyEvent::Handle> has two queues per file handle, a read and a |
745 |
|
|
write queue. The write queue queues pending data that waits to be written |
746 |
|
|
to the file handle. And the read queue queues reading callbacks. For more |
747 |
|
|
details see the documentation L<AnyEvent::Handle> about the READ QUEUE and |
748 |
|
|
WRITE QUEUE. |
749 |
|
|
|
750 |
|
|
my ($handle) = @_; |
751 |
|
|
|
752 |
|
|
if ($handle->rbuf =~ s/^.*?\bend\b.*$//s) { |
753 |
|
|
print "got 'end', existing...\n"; |
754 |
|
|
$end_prog->broadcast; |
755 |
|
|
return 1 |
756 |
|
|
} |
757 |
|
|
|
758 |
|
|
0 |
759 |
|
|
}); |
760 |
|
|
|
761 |
|
|
The actual callback waits until the word 'end' has been seen in the data |
762 |
|
|
received on standard input. Once we encounter the stop word 'end' we |
763 |
|
|
remove everything from the read buffer and call the condition variable |
764 |
|
|
we setup earlier, that signals our 'end of program' condition. And the |
765 |
|
|
callback returns with a true value, that signals we are done with reading |
766 |
|
|
all the data we were interested in (all data until the word 'end' has been |
767 |
|
|
seen). |
768 |
|
|
|
769 |
|
|
In all other cases, when the stop word has not been seen yet, we just |
770 |
|
|
return a false value, to indicate that we are not finished yet. |
771 |
|
|
|
772 |
|
|
The C<rbuf> method returns our read buffer, that we can directly modify as |
773 |
|
|
lvalue. Alternatively we also could have written: |
774 |
|
|
|
775 |
|
|
if ($handle->{rbuf} =~ s/^.*?\bend\b.*$//s) { |
776 |
|
|
|
777 |
|
|
The last line will wait for the condition that our program wants to exit: |
778 |
|
|
|
779 |
|
|
$end_prog->recv; |
780 |
|
|
|
781 |
|
|
The call to C<recv> will setup an event loop for us and wait for IO, timer |
782 |
|
|
or signal events and will handle them until the condition gets sent (by |
783 |
|
|
calling its C<send> method). |
784 |
|
|
|
785 |
|
|
The key points to learn from this example are: |
786 |
|
|
|
787 |
|
|
=over 4 |
788 |
|
|
|
789 |
|
|
=item * Condition variables are used to start an event loop. |
790 |
|
|
|
791 |
|
|
=item * How to registering some basic callbacks on AnyEvent::Handle's. |
792 |
|
|
|
793 |
|
|
=item * How to process data in the read buffer. |
794 |
|
|
|
795 |
|
|
=back |
796 |
|
|
|