1 |
root |
1.21 |
=head1 NAME |
2 |
|
|
|
3 |
|
|
AnyEvent::Intro - an introductory tutorial to AnyEvent |
4 |
|
|
|
5 |
root |
1.2 |
=head1 Introduction to AnyEvent |
6 |
root |
1.1 |
|
7 |
root |
1.2 |
This is a tutorial that will introduce you to the features of AnyEvent. |
8 |
root |
1.1 |
|
9 |
root |
1.2 |
The first part introduces the core AnyEvent module (after swamping you a |
10 |
root |
1.25 |
bit in evangelism), which might already provide all you ever need: If you |
11 |
root |
1.17 |
are only interested in AnyEvent's event handling capabilities, read no |
12 |
|
|
further. |
13 |
root |
1.1 |
|
14 |
root |
1.2 |
The second part focuses on network programming using sockets, for which |
15 |
root |
1.17 |
AnyEvent offers a lot of support you can use, and a lot of workarounds |
16 |
|
|
around portability quirks. |
17 |
root |
1.2 |
|
18 |
|
|
|
19 |
|
|
=head1 What is AnyEvent? |
20 |
|
|
|
21 |
root |
1.10 |
If you don't care for the whys and want to see code, skip this section! |
22 |
root |
1.2 |
|
23 |
|
|
AnyEvent is first of all just a framework to do event-based |
24 |
|
|
programming. Typically such frameworks are an all-or-nothing thing: If you |
25 |
|
|
use one such framework, you can't (easily, or even at all) use another in |
26 |
|
|
the same program. |
27 |
|
|
|
28 |
root |
1.27 |
AnyEvent is different - it is a thin abstraction layer on top of other |
29 |
root |
1.25 |
event loops, just like DBI is an abstraction of many different database |
30 |
|
|
APIs. Its main purpose is to move the choice of the underlying framework |
31 |
|
|
(the event loop) from the module author to the program author using the |
32 |
|
|
module. |
33 |
root |
1.2 |
|
34 |
|
|
That means you can write code that uses events to control what it |
35 |
|
|
does, without forcing other code in the same program to use the same |
36 |
|
|
underlying framework as you do - i.e. you can create a Perl module |
37 |
|
|
that is event-based using AnyEvent, and users of that module can still |
38 |
root |
1.25 |
choose between using L<Gtk2>, L<Tk>, L<Event> (or run inside Irssi or |
39 |
|
|
rxvt-unicode) or any other supported event loop. AnyEvent even comes with |
40 |
|
|
its own pure-perl event loop implementation, so your code works regardless |
41 |
|
|
of other modules that might or might not be installed. The latter is |
42 |
|
|
important, as AnyEvent does not have any hard dependencies to other |
43 |
|
|
modules, which makes it easy to install, for example, when you lack a C |
44 |
root |
1.28 |
compiler. No matter what environment, AnyEvent will just cope with it. |
45 |
root |
1.25 |
|
46 |
|
|
A typical limitation of existing Perl modules such as L<Net::IRC> is that |
47 |
root |
1.28 |
they come with their own event loop: In L<Net::IRC>, a program which uses |
48 |
root |
1.25 |
it needs to start the event loop of L<Net::IRC>. That means that one |
49 |
|
|
cannot integrate this module into a L<Gtk2> GUI for instance, as that |
50 |
|
|
module, too, enforces the use of its own event loop (namely L<Glib>). |
51 |
|
|
|
52 |
|
|
Another example is L<LWP>: it provides no event interface at all. It's |
53 |
|
|
a pure blocking HTTP (and FTP etc.) client library, which usually means |
54 |
|
|
that you either have to start another process or have to fork for a HTTP |
55 |
|
|
request, or use threads (e.g. L<Coro::LWP>), if you want to do something |
56 |
|
|
else while waiting for the request to finish. |
57 |
|
|
|
58 |
|
|
The motivation behind these designs is often that a module doesn't want |
59 |
|
|
to depend on some complicated XS-module (Net::IRC), or that it doesn't |
60 |
|
|
want to force the user to use some specific event loop at all (LWP), out |
61 |
|
|
of fear of severly limiting the usefulness of the module: If your module |
62 |
|
|
requires Glib, it will not run in a Tk program. |
63 |
root |
1.1 |
|
64 |
root |
1.25 |
L<AnyEvent> solves this dilemma, by B<not> forcing module authors to |
65 |
|
|
either: |
66 |
root |
1.1 |
|
67 |
|
|
=over 4 |
68 |
|
|
|
69 |
root |
1.25 |
=item - write their own event loop (because it guarantees the availability |
70 |
|
|
of an event loop everywhere - even on windows with no extra modules |
71 |
|
|
installed). |
72 |
root |
1.1 |
|
73 |
root |
1.25 |
=item - choose one specific event loop (because AnyEvent works with most |
74 |
|
|
event loops available for Perl). |
75 |
root |
1.1 |
|
76 |
|
|
=back |
77 |
|
|
|
78 |
root |
1.25 |
If the module author uses L<AnyEvent> for all his (or her) event needs |
79 |
|
|
(IO events, timers, signals, ...) then all other modules can just use |
80 |
|
|
his module and don't have to choose an event loop or adapt to his event |
81 |
|
|
loop. The choice of the event loop is ultimately made by the program |
82 |
|
|
author who uses all the modules and writes the main program. And even |
83 |
|
|
there he doesn't have to choose, he can just let L<AnyEvent> choose the |
84 |
|
|
most efficient event loop available on the system. |
85 |
root |
1.1 |
|
86 |
|
|
Read more about this in the main documentation of the L<AnyEvent> module. |
87 |
|
|
|
88 |
|
|
|
89 |
root |
1.2 |
=head1 Introduction to Event-Based Programming |
90 |
|
|
|
91 |
|
|
So what exactly is programming using events? It quite simply means that |
92 |
|
|
instead of your code actively waiting for something, such as the user |
93 |
|
|
entering something on STDIN: |
94 |
|
|
|
95 |
|
|
$| = 1; print "enter your name> "; |
96 |
|
|
|
97 |
|
|
my $name = <STDIN>; |
98 |
|
|
|
99 |
|
|
You instead tell your event framework to notify you in the event of some |
100 |
|
|
data being available on STDIN, by using a callback mechanism: |
101 |
|
|
|
102 |
|
|
use AnyEvent; |
103 |
|
|
|
104 |
|
|
$| = 1; print "enter your name> "; |
105 |
|
|
|
106 |
|
|
my $name; |
107 |
|
|
|
108 |
|
|
my $wait_for_input = AnyEvent->io ( |
109 |
|
|
fh => \*STDIN, # which file handle to check |
110 |
|
|
poll => "r", # which event to wait for ("r"ead data) |
111 |
|
|
cb => sub { # what callback to execute |
112 |
|
|
$name = <STDIN>; # read it |
113 |
|
|
} |
114 |
|
|
); |
115 |
|
|
|
116 |
|
|
# do something else here |
117 |
|
|
|
118 |
|
|
Looks more complicated, and surely is, but the advantage of using events |
119 |
root |
1.22 |
is that your program can do something else instead of waiting for input |
120 |
|
|
(side note: combining AnyEvent with a thread package such as Coro can |
121 |
|
|
recoup much of the simplicity, effectively getting the best of two |
122 |
|
|
worlds). |
123 |
|
|
|
124 |
|
|
Waiting as done in the first example is also called "blocking" the process |
125 |
|
|
because you "block"/keep your process from executing anything else while |
126 |
|
|
you do so. |
127 |
root |
1.2 |
|
128 |
root |
1.22 |
The second example avoids blocking by only registering interest in a read |
129 |
root |
1.28 |
event, which is fast and doesn't block your process. The callback will |
130 |
|
|
be called only when data is available and can be read without blocking. |
131 |
root |
1.2 |
|
132 |
|
|
The "interest" is represented by an object returned by C<< AnyEvent->io |
133 |
root |
1.28 |
>> called a "watcher" object - thus named because it "watches" your |
134 |
root |
1.2 |
file handle (or other event sources) for the event you are interested in. |
135 |
|
|
|
136 |
|
|
In the example above, we create an I/O watcher by calling the C<< |
137 |
root |
1.28 |
AnyEvent->io >> method. A lack of further interest in some event is |
138 |
|
|
expressed by simply forgetting about its watcher, for example by |
139 |
|
|
C<undef>-ing the only variable it is stored in. AnyEvent will |
140 |
|
|
automatically clean up the watcher if it is no longer used, much like |
141 |
|
|
Perl closes your file handles if you no longer use them anywhere. |
142 |
root |
1.2 |
|
143 |
root |
1.18 |
=head3 A short note on callbacks |
144 |
|
|
|
145 |
|
|
A common issue that hits people is the problem of passing parameters |
146 |
|
|
to callbacks. Programmers used to languages such as C or C++ are often |
147 |
|
|
used to a style where one passes the address of a function (a function |
148 |
|
|
reference) and some data value, e.g.: |
149 |
|
|
|
150 |
|
|
sub callback { |
151 |
|
|
my ($arg) = @_; |
152 |
|
|
|
153 |
|
|
$arg->method; |
154 |
|
|
} |
155 |
|
|
|
156 |
|
|
my $arg = ...; |
157 |
|
|
|
158 |
|
|
call_me_back_later \&callback, $arg; |
159 |
|
|
|
160 |
|
|
This is clumsy, as the place where behaviour is specified (when the |
161 |
|
|
callback is registered) is often far away from the place where behaviour |
162 |
|
|
is implemented. It also doesn't use Perl syntax to invoke the code. There |
163 |
|
|
is also an abstraction penalty to pay as one has to I<name> the callback, |
164 |
|
|
which often is unnecessary and leads to nonsensical or duplicated names. |
165 |
|
|
|
166 |
|
|
In Perl, one can specify behaviour much more directly by using |
167 |
|
|
I<closures>. Closures are code blocks that take a reference to the |
168 |
root |
1.28 |
enclosing scope(s) when they are created. This means lexical variables |
169 |
|
|
in scope when a closure is created can be used inside the closure: |
170 |
root |
1.18 |
|
171 |
|
|
my $arg = ...; |
172 |
|
|
|
173 |
|
|
call_me_back_later sub { $arg->method }; |
174 |
|
|
|
175 |
root |
1.22 |
Under most circumstances, closures are faster, use fewer resources and |
176 |
root |
1.18 |
result in much clearer code then the traditional approach. Faster, |
177 |
|
|
because parameter passing and storing them in local variables in Perl |
178 |
root |
1.22 |
is relatively slow. Fewer resources, because closures take references |
179 |
|
|
to existing variables without having to create new ones, and clearer |
180 |
|
|
code because it is immediately obvious that the second example calls the |
181 |
root |
1.18 |
C<method> method when the callback is invoked. |
182 |
|
|
|
183 |
|
|
Apart from these, the strongest argument for using closures with AnyEvent |
184 |
|
|
is that AnyEvent does not allow passing parameters to the callback, so |
185 |
|
|
closures are the only way to achieve that in most cases :-> |
186 |
|
|
|
187 |
|
|
|
188 |
root |
1.31 |
=head3 A little hint to catch mistakes |
189 |
root |
1.19 |
|
190 |
root |
1.31 |
AnyEvent does not check the parameters you pass in, at least not by |
191 |
|
|
default. to enable checking, simply start your program with C<AE_STRICT=1> |
192 |
|
|
in the environment, or put C<use AnyEvent::Strict> near the top of your |
193 |
|
|
program: |
194 |
root |
1.19 |
|
195 |
root |
1.31 |
AE_STRICT=1 perl myprogram |
196 |
root |
1.19 |
|
197 |
root |
1.31 |
You can find more info on this and additional debugging aids later in this |
198 |
|
|
introduction. |
199 |
root |
1.19 |
|
200 |
|
|
|
201 |
root |
1.2 |
=head2 Condition Variables |
202 |
|
|
|
203 |
root |
1.22 |
Back to the I/O watcher example: The code is not yet a fully working |
204 |
|
|
program, and will not work as-is. The reason is that your callback will |
205 |
root |
1.28 |
not be invoked out of the blue; you have to run the event loop first. |
206 |
|
|
Also, event-based programs need to block sometimes too, such as when |
207 |
|
|
there is nothing to do, and everything is waiting for new events to |
208 |
|
|
arrive. |
209 |
root |
1.2 |
|
210 |
|
|
In AnyEvent, this is done using condition variables. Condition variables |
211 |
|
|
are named "condition variables" because they represent a condition that is |
212 |
|
|
initially false and needs to be fulfilled. |
213 |
|
|
|
214 |
root |
1.10 |
You can also call them "merge points", "sync points", "rendezvous ports" |
215 |
root |
1.27 |
or even callbacks and many other things (and they are often called these |
216 |
|
|
names in other frameworks). The important point is that you can create them |
217 |
root |
1.10 |
freely and later wait for them to become true. |
218 |
root |
1.2 |
|
219 |
|
|
Condition variables have two sides - one side is the "producer" of the |
220 |
root |
1.18 |
condition (whatever code detects and flags the condition), the other side |
221 |
|
|
is the "consumer" (the code that waits for that condition). |
222 |
root |
1.2 |
|
223 |
|
|
In our example in the previous section, the producer is the event callback |
224 |
root |
1.18 |
and there is no consumer yet - let's change that right now: |
225 |
root |
1.2 |
|
226 |
|
|
use AnyEvent; |
227 |
|
|
|
228 |
|
|
$| = 1; print "enter your name> "; |
229 |
|
|
|
230 |
|
|
my $name; |
231 |
|
|
|
232 |
|
|
my $name_ready = AnyEvent->condvar; |
233 |
|
|
|
234 |
|
|
my $wait_for_input = AnyEvent->io ( |
235 |
|
|
fh => \*STDIN, |
236 |
|
|
poll => "r", |
237 |
|
|
cb => sub { |
238 |
|
|
$name = <STDIN>; |
239 |
|
|
$name_ready->send; |
240 |
|
|
} |
241 |
|
|
); |
242 |
|
|
|
243 |
|
|
# do something else here |
244 |
|
|
|
245 |
|
|
# now wait until the name is available: |
246 |
|
|
$name_ready->recv; |
247 |
|
|
|
248 |
root |
1.29 |
undef $wait_for_input; # watcher no longer needed |
249 |
root |
1.2 |
|
250 |
|
|
print "your name is $name\n"; |
251 |
|
|
|
252 |
|
|
This program creates an AnyEvent condvar by calling the C<< |
253 |
|
|
AnyEvent->condvar >> method. It then creates a watcher as usual, but |
254 |
root |
1.28 |
inside the callback it C<send>s the C<$name_ready> condition variable, |
255 |
root |
1.22 |
which causes whoever is waiting on it to continue. |
256 |
root |
1.2 |
|
257 |
root |
1.22 |
The "whoever" in this case is the code that follows, which calls C<< |
258 |
root |
1.2 |
$name_ready->recv >>: The producer calls C<send>, the consumer calls |
259 |
|
|
C<recv>. |
260 |
|
|
|
261 |
|
|
If there is no C<$name> available yet, then the call to C<< |
262 |
|
|
$name_ready->recv >> will halt your program until the condition becomes |
263 |
|
|
true. |
264 |
|
|
|
265 |
|
|
As the names C<send> and C<recv> imply, you can actually send and receive |
266 |
|
|
data using this, for example, the above code could also be written like |
267 |
|
|
this, without an extra variable to store the name in: |
268 |
|
|
|
269 |
|
|
use AnyEvent; |
270 |
|
|
|
271 |
|
|
$| = 1; print "enter your name> "; |
272 |
|
|
|
273 |
|
|
my $name_ready = AnyEvent->condvar; |
274 |
|
|
|
275 |
|
|
my $wait_for_input = AnyEvent->io ( |
276 |
|
|
fh => \*STDIN, poll => "r", |
277 |
root |
1.20 |
cb => sub { $name_ready->send (scalar <STDIN>) } |
278 |
root |
1.2 |
); |
279 |
|
|
|
280 |
|
|
# do something else here |
281 |
|
|
|
282 |
|
|
# now wait and fetch the name |
283 |
|
|
my $name = $name_ready->recv; |
284 |
|
|
|
285 |
root |
1.30 |
undef $wait_for_input; # watcher no longer needed |
286 |
root |
1.2 |
|
287 |
|
|
print "your name is $name\n"; |
288 |
|
|
|
289 |
root |
1.28 |
You can pass any number of arguments to C<send>, and every subsequent |
290 |
|
|
call to C<recv> will return them. |
291 |
root |
1.2 |
|
292 |
|
|
=head2 The "main loop" |
293 |
|
|
|
294 |
|
|
Most event-based frameworks have something called a "main loop" or "event |
295 |
|
|
loop run function" or something similar. |
296 |
|
|
|
297 |
|
|
Just like in C<recv> AnyEvent, these functions need to be called |
298 |
|
|
eventually so that your event loop has a chance of actually looking for |
299 |
root |
1.28 |
the events you are interested in. |
300 |
root |
1.2 |
|
301 |
|
|
For example, in a L<Gtk2> program, the above example could also be written |
302 |
|
|
like this: |
303 |
|
|
|
304 |
|
|
use Gtk2 -init; |
305 |
|
|
use AnyEvent; |
306 |
|
|
|
307 |
|
|
############################################ |
308 |
|
|
# create a window and some label |
309 |
|
|
|
310 |
|
|
my $window = new Gtk2::Window "toplevel"; |
311 |
|
|
$window->add (my $label = new Gtk2::Label "soon replaced by name"); |
312 |
|
|
|
313 |
|
|
$window->show_all; |
314 |
|
|
|
315 |
|
|
############################################ |
316 |
|
|
# do our AnyEvent stuff |
317 |
|
|
|
318 |
|
|
$| = 1; print "enter your name> "; |
319 |
|
|
|
320 |
|
|
my $name_ready = AnyEvent->condvar; |
321 |
|
|
|
322 |
|
|
my $wait_for_input = AnyEvent->io ( |
323 |
|
|
fh => \*STDIN, poll => "r", |
324 |
|
|
cb => sub { |
325 |
|
|
# set the label |
326 |
|
|
$label->set_text (scalar <STDIN>); |
327 |
|
|
print "enter another name> "; |
328 |
|
|
} |
329 |
|
|
); |
330 |
|
|
|
331 |
|
|
############################################ |
332 |
|
|
# Now enter Gtk2's event loop |
333 |
|
|
|
334 |
|
|
main Gtk2; |
335 |
|
|
|
336 |
|
|
No condition variable anywhere in sight - instead, we just read a line |
337 |
|
|
from STDIN and replace the text in the label. In fact, since nobody |
338 |
root |
1.28 |
C<undef>s C<$wait_for_input> you can enter multiple lines. |
339 |
root |
1.2 |
|
340 |
|
|
Instead of waiting for a condition variable, the program enters the Gtk2 |
341 |
|
|
main loop by calling C<< Gtk2->main >>, which will block the program and |
342 |
|
|
wait for events to arrive. |
343 |
|
|
|
344 |
root |
1.27 |
This also shows that AnyEvent is quite flexible - you didn't have to do |
345 |
|
|
anything to make the AnyEvent watcher use Gtk2 (actually Glib) - it just |
346 |
root |
1.2 |
worked. |
347 |
|
|
|
348 |
|
|
Admittedly, the example is a bit silly - who would want to read names |
349 |
root |
1.28 |
from standard input in a Gtk+ application? But imagine that instead of |
350 |
|
|
doing that, you make an HTTP request in the background and display its |
351 |
|
|
results. In fact, with event-based programming you can make many |
352 |
root |
1.27 |
HTTP requests in parallel in your program and still provide feedback to |
353 |
root |
1.2 |
the user and stay interactive. |
354 |
|
|
|
355 |
root |
1.22 |
And in the next part you will see how to do just that - by implementing an |
356 |
root |
1.2 |
HTTP request, on our own, with the utility modules AnyEvent comes with. |
357 |
|
|
|
358 |
root |
1.4 |
Before that, however, let's briefly look at how you would write your |
359 |
root |
1.27 |
program using only AnyEvent, without ever calling some other event |
360 |
root |
1.2 |
loop's run function. |
361 |
|
|
|
362 |
root |
1.22 |
In the example using condition variables, we used those to start waiting |
363 |
|
|
for events, and in fact, condition variables are the solution: |
364 |
root |
1.2 |
|
365 |
|
|
my $quit_program = AnyEvent->condvar; |
366 |
|
|
|
367 |
|
|
# create AnyEvent watchers (or not) here |
368 |
|
|
|
369 |
|
|
$quit_program->recv; |
370 |
|
|
|
371 |
root |
1.22 |
If any of your watcher callbacks decide to quit (this is often |
372 |
root |
1.28 |
called an "unloop" in other frameworks), they can just call C<< |
373 |
root |
1.22 |
$quit_program->send >>. Of course, they could also decide not to and |
374 |
root |
1.28 |
call C<exit> instead, or they could decide never to quit (e.g. in a |
375 |
|
|
long-running daemon program). |
376 |
root |
1.2 |
|
377 |
root |
1.22 |
If you don't need some clean quit functionality and just want to run the |
378 |
root |
1.28 |
event loop, you can do this: |
379 |
root |
1.2 |
|
380 |
|
|
AnyEvent->condvar->recv; |
381 |
|
|
|
382 |
root |
1.28 |
And this is, in fact, the closest to the idea of a main loop run |
383 |
|
|
function that AnyEvent offers. |
384 |
root |
1.2 |
|
385 |
|
|
=head2 Timers and other event sources |
386 |
|
|
|
387 |
root |
1.28 |
So far, we have used only I/O watchers. These are useful mainly to find |
388 |
root |
1.26 |
out whether a socket has data to read, or space to write more data. On sane |
389 |
root |
1.2 |
operating systems this also works for console windows/terminals (typically |
390 |
|
|
on standard input), serial lines, all sorts of other devices, basically |
391 |
|
|
almost everything that has a file descriptor but isn't a file itself. (As |
392 |
|
|
usual, "sane" excludes windows - on that platform you would need different |
393 |
root |
1.10 |
functions for all of these, complicating code immensely - think "socket |
394 |
root |
1.2 |
only" on windows). |
395 |
|
|
|
396 |
root |
1.10 |
However, I/O is not everything - the second most important event source is |
397 |
root |
1.2 |
the clock. For example when doing an HTTP request you might want to time |
398 |
root |
1.10 |
out when the server doesn't answer within some predefined amount of time. |
399 |
root |
1.2 |
|
400 |
|
|
In AnyEvent, timer event watchers are created by calling the C<< |
401 |
|
|
AnyEvent->timer >> method: |
402 |
|
|
|
403 |
|
|
use AnyEvent; |
404 |
|
|
|
405 |
|
|
my $cv = AnyEvent->condvar; |
406 |
|
|
|
407 |
|
|
my $wait_one_and_a_half_seconds = AnyEvent->timer ( |
408 |
|
|
after => 1.5, # after how many seconds to invoke the cb? |
409 |
|
|
cb => sub { # the callback to invoke |
410 |
|
|
$cv->send; |
411 |
|
|
}, |
412 |
|
|
); |
413 |
|
|
|
414 |
root |
1.10 |
# can do something else here |
415 |
root |
1.2 |
|
416 |
|
|
# now wait till our time has come |
417 |
|
|
$cv->recv; |
418 |
|
|
|
419 |
|
|
Unlike I/O watchers, timers are only interested in the amount of seconds |
420 |
root |
1.22 |
they have to wait. When (at least) that amount of time has passed, |
421 |
|
|
AnyEvent will invoke your callback. |
422 |
root |
1.2 |
|
423 |
|
|
Unlike I/O watchers, which will call your callback as many times as there |
424 |
root |
1.22 |
is data available, timers are normally one-shot: after they have "fired" |
425 |
|
|
once and invoked your callback, they are dead and no longer do anything. |
426 |
root |
1.2 |
|
427 |
|
|
To get a repeating timer, such as a timer firing roughly once per second, |
428 |
root |
1.22 |
you can specify an C<interval> parameter: |
429 |
root |
1.2 |
|
430 |
root |
1.22 |
my $once_per_second = AnyEvent->timer ( |
431 |
|
|
after => 0, # first invoke ASAP |
432 |
|
|
interval => 1, # then invoke every second |
433 |
|
|
cb => sub { # the callback to invoke |
434 |
|
|
$cv->send; |
435 |
|
|
}, |
436 |
|
|
); |
437 |
root |
1.2 |
|
438 |
|
|
=head3 More esoteric sources |
439 |
|
|
|
440 |
|
|
AnyEvent also has some other, more esoteric event sources you can tap |
441 |
root |
1.22 |
into: signal, child and idle watchers. |
442 |
root |
1.2 |
|
443 |
root |
1.28 |
Signal watchers can be used to wait for "signal events", which means |
444 |
|
|
your process was sent a signal (such as C<SIGTERM> or C<SIGUSR1>). |
445 |
root |
1.2 |
|
446 |
root |
1.22 |
Child-process watchers wait for a child process to exit. They are useful |
447 |
|
|
when you fork a separate process and need to know when it exits, but you |
448 |
root |
1.28 |
do not want to wait for that by blocking. |
449 |
root |
1.22 |
|
450 |
|
|
Idle watchers invoke their callback when the event loop has handled all |
451 |
|
|
outstanding events, polled for new events and didn't find any, i.e., when |
452 |
|
|
your process is otherwise idle. They are useful if you want to do some |
453 |
|
|
non-trivial data processing that can be done when your program doesn't |
454 |
|
|
have anything better to do. |
455 |
|
|
|
456 |
|
|
All these watcher types are described in detail in the main L<AnyEvent> |
457 |
|
|
manual page. |
458 |
|
|
|
459 |
|
|
Sometimes you also need to know what the current time is: C<< |
460 |
|
|
AnyEvent->now >> returns the time the event toolkit uses to schedule |
461 |
|
|
relative timers, and is usually what you want. It is often cached (which |
462 |
|
|
means it can be a bit outdated). In that case, you can use the more costly |
463 |
|
|
C<< AnyEvent->time >> method which will ask your operating system for the |
464 |
|
|
current time, which is slower, but also more up to date. |
465 |
root |
1.2 |
|
466 |
root |
1.31 |
|
467 |
root |
1.2 |
=head1 Network programming and AnyEvent |
468 |
|
|
|
469 |
root |
1.3 |
So far you have seen how to register event watchers and handle events. |
470 |
root |
1.1 |
|
471 |
root |
1.22 |
This is a great foundation to write network clients and servers, and might |
472 |
|
|
be all that your module (or program) ever requires, but writing your own |
473 |
|
|
I/O buffering again and again becomes tedious, not to mention that it |
474 |
|
|
attracts errors. |
475 |
root |
1.3 |
|
476 |
|
|
While the core L<AnyEvent> module is still small and self-contained, |
477 |
|
|
the distribution comes with some very useful utility modules such as |
478 |
|
|
L<AnyEvent::Handle>, L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can |
479 |
root |
1.28 |
make your life as a non-blocking network programmer a lot easier. |
480 |
root |
1.3 |
|
481 |
root |
1.28 |
Here is a quick overview of these three modules: |
482 |
root |
1.4 |
|
483 |
|
|
=head2 L<AnyEvent::DNS> |
484 |
|
|
|
485 |
|
|
This module allows fully asynchronous DNS resolution. It is used mainly by |
486 |
|
|
L<AnyEvent::Socket> to resolve hostnames and service ports for you, but is |
487 |
|
|
a great way to do other DNS resolution tasks, such as reverse lookups of |
488 |
|
|
IP addresses for log files. |
489 |
root |
1.1 |
|
490 |
root |
1.2 |
=head2 L<AnyEvent::Handle> |
491 |
root |
1.1 |
|
492 |
root |
1.22 |
This module handles non-blocking IO on (socket-, pipe- etc.) file handles |
493 |
|
|
in an event based manner. It provides a wrapper object around your file |
494 |
|
|
handle that provides queueing and buffering of incoming and outgoing data |
495 |
|
|
for you. |
496 |
root |
1.1 |
|
497 |
root |
1.4 |
It also implements the most common data formats, such as text lines, or |
498 |
|
|
fixed and variable-width data blocks. |
499 |
root |
1.1 |
|
500 |
root |
1.2 |
=head2 L<AnyEvent::Socket> |
501 |
root |
1.1 |
|
502 |
|
|
This module provides you with functions that handle socket creation |
503 |
|
|
and IP address magic. The two main functions are C<tcp_connect> and |
504 |
|
|
C<tcp_server>. The former will connect a (streaming) socket to an internet |
505 |
|
|
host for you and the later will make a server socket for you, to accept |
506 |
|
|
connections. |
507 |
|
|
|
508 |
|
|
This module also comes with transparent IPv6 support, this means: If you |
509 |
|
|
write your programs with this module, you will be IPv6 ready without doing |
510 |
root |
1.4 |
anything special. |
511 |
root |
1.1 |
|
512 |
|
|
It also works around a lot of portability quirks (especially on the |
513 |
|
|
windows platform), which makes it even easier to write your programs in a |
514 |
root |
1.4 |
portable way (did you know that windows uses different error codes for all |
515 |
|
|
socket functions and that Perl does not know about these? That "Unknown |
516 |
|
|
error 10022" (which is C<WSAEINVAL>) can mean that our C<connect> call was |
517 |
|
|
successful? That unsuccessful TCP connects might never be reported back |
518 |
|
|
to your program? That C<WSAEINPROGRESS> means your C<connect> call was |
519 |
|
|
ignored instead of being in progress? AnyEvent::Socket works around all of |
520 |
|
|
these Windows/Perl bugs for you). |
521 |
|
|
|
522 |
root |
1.11 |
=head2 Implementing a parallel finger client with non-blocking connects |
523 |
root |
1.16 |
and AnyEvent::Socket |
524 |
root |
1.4 |
|
525 |
|
|
The finger protocol is one of the simplest protocols in use on the |
526 |
|
|
internet. Or in use in the past, as almost nobody uses it anymore. |
527 |
|
|
|
528 |
|
|
It works by connecting to the finger port on another host, writing a |
529 |
|
|
single line with a user name and then reading the finger response, as |
530 |
|
|
specified by that user. OK, RFC 1288 specifies a vastly more complex |
531 |
|
|
protocol, but it basically boils down to this: |
532 |
|
|
|
533 |
root |
1.22 |
# telnet kernel.org finger |
534 |
|
|
Trying 204.152.191.37... |
535 |
|
|
Connected to kernel.org (204.152.191.37). |
536 |
root |
1.4 |
Escape character is '^]'. |
537 |
root |
1.22 |
|
538 |
|
|
The latest stable version of the Linux kernel is: [...] |
539 |
root |
1.4 |
Connection closed by foreign host. |
540 |
|
|
|
541 |
root |
1.22 |
So let's write a little AnyEvent function that makes a finger request: |
542 |
root |
1.4 |
|
543 |
|
|
use AnyEvent; |
544 |
|
|
use AnyEvent::Socket; |
545 |
|
|
|
546 |
|
|
sub finger($$) { |
547 |
|
|
my ($user, $host) = @_; |
548 |
|
|
|
549 |
|
|
# use a condvar to return results |
550 |
|
|
my $cv = AnyEvent->condvar; |
551 |
|
|
|
552 |
|
|
# first, connect to the host |
553 |
|
|
tcp_connect $host, "finger", sub { |
554 |
root |
1.8 |
# the callback receives the socket handle - or nothing |
555 |
root |
1.4 |
my ($fh) = @_ |
556 |
|
|
or return $cv->send; |
557 |
|
|
|
558 |
|
|
# now write the username |
559 |
|
|
syswrite $fh, "$user\015\012"; |
560 |
|
|
|
561 |
|
|
my $response; |
562 |
|
|
|
563 |
|
|
# register a read watcher |
564 |
|
|
my $read_watcher; $read_watcher = AnyEvent->io ( |
565 |
|
|
fh => $fh, |
566 |
|
|
poll => "r", |
567 |
|
|
cb => sub { |
568 |
|
|
my $len = sysread $fh, $response, 1024, length $response; |
569 |
|
|
|
570 |
|
|
if ($len <= 0) { |
571 |
|
|
# we are done, or an error occured, lets ignore the latter |
572 |
|
|
undef $read_watcher; # no longer interested |
573 |
|
|
$cv->send ($response); # send results |
574 |
|
|
} |
575 |
|
|
}, |
576 |
|
|
); |
577 |
|
|
}; |
578 |
|
|
|
579 |
|
|
# pass $cv to the caller |
580 |
|
|
$cv |
581 |
|
|
} |
582 |
|
|
|
583 |
root |
1.11 |
That's a mouthful! Let's dissect this function a bit, first the overall |
584 |
|
|
function and execution flow: |
585 |
root |
1.4 |
|
586 |
|
|
sub finger($$) { |
587 |
|
|
my ($user, $host) = @_; |
588 |
|
|
|
589 |
|
|
# use a condvar to return results |
590 |
|
|
my $cv = AnyEvent->condvar; |
591 |
|
|
|
592 |
|
|
# first, connect to the host |
593 |
|
|
tcp_connect $host, "finger", sub { |
594 |
|
|
... |
595 |
|
|
}; |
596 |
|
|
|
597 |
|
|
$cv |
598 |
|
|
} |
599 |
|
|
|
600 |
root |
1.28 |
This isn't too complicated, just a function with two parameters that |
601 |
|
|
creates a condition variable C<$cv>, initiates a TCP connect to |
602 |
|
|
C<$host>, and returns C<$cv>. The caller can use the returned C<$cv> to |
603 |
|
|
receive the finger response, but one could equally well pass a third |
604 |
|
|
argument, a callback, to the function. |
605 |
root |
1.4 |
|
606 |
root |
1.11 |
Since we are programming event'ish, we do not wait for the connect to |
607 |
|
|
finish - it could block the program for a minute or longer! |
608 |
|
|
|
609 |
root |
1.28 |
Instead, we pass C<tcp_connect> a callback to invoke when the connect is |
610 |
|
|
done. The callback is called with the socket handle as its first |
611 |
|
|
argument if the connect succeeds, and no arguments otherwise. The |
612 |
|
|
important point is that it will always be called as soon as the outcome |
613 |
|
|
of the TCP connect is known. |
614 |
root |
1.11 |
|
615 |
|
|
This style of programming is also called "continuation style": the |
616 |
root |
1.22 |
"continuation" is simply the way the program continues - normally at the |
617 |
|
|
next line after some statement (the exception is loops or things like |
618 |
|
|
C<return>). When we are interested in events, however, we instead specify |
619 |
|
|
the "continuation" of our program by passing a closure, which makes that |
620 |
|
|
closure the "continuation" of the program. |
621 |
|
|
|
622 |
|
|
The C<tcp_connect> call is like saying "return now, and when the |
623 |
root |
1.28 |
connection is established or the attempt failed, continue there". |
624 |
root |
1.4 |
|
625 |
root |
1.11 |
Now let's look at the callback/closure in more detail: |
626 |
root |
1.4 |
|
627 |
root |
1.11 |
# the callback receives the socket handle - or nothing |
628 |
root |
1.4 |
my ($fh) = @_ |
629 |
|
|
or return $cv->send; |
630 |
|
|
|
631 |
root |
1.28 |
The first thing the callback does is to save the socket handle in |
632 |
root |
1.5 |
C<$fh>. When there was an error (no arguments), then our instinct as |
633 |
root |
1.11 |
expert Perl programmers would tell us to C<die>: |
634 |
root |
1.4 |
|
635 |
|
|
my ($fh) = @_ |
636 |
|
|
or die "$host: $!"; |
637 |
root |
1.1 |
|
638 |
root |
1.11 |
While this would give good feedback to the user (if he happens to watch |
639 |
|
|
standard error), our program would probably stop working here, as we never |
640 |
|
|
report the results to anybody, certainly not the caller of our C<finger> |
641 |
|
|
function, and most event loops continue even after a C<die>! |
642 |
|
|
|
643 |
|
|
This is why we instead C<return>, but also call C<< $cv->send >> without |
644 |
|
|
any arguments to signal to the condvar consumer that something bad has |
645 |
root |
1.22 |
happened. The return value of C<< $cv->send >> is irrelevant, as is |
646 |
root |
1.28 |
the return value of our callback. The C<return> statement is used for |
647 |
|
|
the side effect of, well, returning immediately from the callback. |
648 |
|
|
Checking for errors and handling them this way is very common, which is |
649 |
|
|
why this compact idiom is so handy. |
650 |
root |
1.4 |
|
651 |
|
|
As the next step in the finger protocol, we send the username to the |
652 |
root |
1.22 |
finger daemon on the other side of our connection (the kernel.org finger |
653 |
|
|
service doesn't actually wait for a username, but the net is running out |
654 |
|
|
of finger servers fast): |
655 |
root |
1.4 |
|
656 |
|
|
syswrite $fh, "$user\015\012"; |
657 |
|
|
|
658 |
root |
1.11 |
Note that this isn't 100% clean socket programming - the socket could, |
659 |
|
|
for whatever reasons, not accept our data. When writing a small amount |
660 |
|
|
of data like in this example it doesn't matter, as a socket buffer is |
661 |
|
|
almost always big enough for a mere "username", but for real-world |
662 |
|
|
cases you might need to implement some kind of write buffering - or use |
663 |
|
|
L<AnyEvent::Handle>, which handles these matters for you, as shown in the |
664 |
|
|
next section. |
665 |
root |
1.4 |
|
666 |
root |
1.28 |
What we I<do> have to do is implement our own read buffer - the response |
667 |
root |
1.4 |
data could arrive late or in multiple chunks, and we cannot just wait for |
668 |
|
|
it (event-based programming, you know?). |
669 |
|
|
|
670 |
|
|
To do that, we register a read watcher on the socket which waits for data: |
671 |
|
|
|
672 |
|
|
my $read_watcher; $read_watcher = AnyEvent->io ( |
673 |
|
|
fh => $fh, |
674 |
|
|
poll => "r", |
675 |
|
|
|
676 |
|
|
There is a trick here, however: the read watcher isn't stored in a global |
677 |
|
|
variable, but in a local one - if the callback returns, it would normally |
678 |
|
|
destroy the variable and its contents, which would in turn unregister our |
679 |
root |
1.5 |
watcher. |
680 |
root |
1.4 |
|
681 |
root |
1.28 |
To avoid that, we refer to the watcher variable in the watcher callback. |
682 |
|
|
This means that, when the C<tcp_connect> callback returns, perl thinks |
683 |
|
|
(quite correctly) that the read watcher is still in use - namely inside |
684 |
|
|
the inner callback - and thus keeps it alive even if nothing else in the |
685 |
|
|
program refers to it anymore (it is much like Baron Münchhausen keeping |
686 |
|
|
himself from dying by pulling himself out of a swamp). |
687 |
root |
1.4 |
|
688 |
root |
1.11 |
The trick, however, is that instead of: |
689 |
|
|
|
690 |
|
|
my $read_watcher = AnyEvent->io (... |
691 |
|
|
|
692 |
|
|
The program does: |
693 |
|
|
|
694 |
|
|
my $read_watcher; $read_watcher = AnyEvent->io (... |
695 |
|
|
|
696 |
|
|
The reason for this is a quirk in the way Perl works: variable names |
697 |
|
|
declared with C<my> are only visible in the I<next> statement. If the |
698 |
|
|
whole C<< AnyEvent->io >> call, including the callback, would be done in |
699 |
|
|
a single statement, the callback could not refer to the C<$read_watcher> |
700 |
root |
1.28 |
variable to C<undef>ine it, so it is done in two statements. |
701 |
root |
1.11 |
|
702 |
root |
1.28 |
Whether you'd want to format it like this is of course a matter of style. |
703 |
|
|
This way emphasizes that the declaration and assignment really are one |
704 |
root |
1.11 |
logical statement. |
705 |
|
|
|
706 |
root |
1.4 |
The callback itself calls C<sysread> for as many times as necessary, until |
707 |
root |
1.11 |
C<sysread> returns either an error or end-of-file: |
708 |
root |
1.4 |
|
709 |
|
|
cb => sub { |
710 |
|
|
my $len = sysread $fh, $response, 1024, length $response; |
711 |
|
|
|
712 |
|
|
if ($len <= 0) { |
713 |
|
|
|
714 |
root |
1.28 |
Note that C<sysread> has the ability to append data it reads to a scalar |
715 |
|
|
if we specify an offset, a feature which we make use of in this example. |
716 |
root |
1.4 |
|
717 |
|
|
When C<sysread> indicates we are done, the callback C<undef>ines |
718 |
root |
1.28 |
the watcher and then C<send>s the response data to the condition |
719 |
root |
1.4 |
variable. All this has the following effects: |
720 |
|
|
|
721 |
|
|
Undefining the watcher destroys it, as our callback was the only one still |
722 |
|
|
having a reference to it. When the watcher gets destroyed, it destroys the |
723 |
|
|
callback, which in turn means the C<$fh> handle is no longer used, so that |
724 |
|
|
gets destroyed as well. The result is that all resources will be nicely |
725 |
|
|
cleaned up by perl for us. |
726 |
|
|
|
727 |
|
|
=head3 Using the finger client |
728 |
|
|
|
729 |
root |
1.5 |
Now, we could probably write the same finger client in a simpler way if |
730 |
|
|
we used C<IO::Socket::INET>, ignored the problem of multiple hosts and |
731 |
|
|
ignored IPv6 and a few other things that C<tcp_connect> handles for us. |
732 |
root |
1.4 |
|
733 |
|
|
But the main advantage is that we can not only run this finger function in |
734 |
|
|
the background, we even can run multiple sessions in parallel, like this: |
735 |
|
|
|
736 |
|
|
my $f1 = finger "trouble", "noc.dfn.de"; # check for trouble tickets |
737 |
|
|
my $f2 = finger "1736" , "noc.dfn.de"; # fetch ticket 1736 |
738 |
root |
1.22 |
my $f3 = finger "hpa" , "kernel.org"; # finger hpa |
739 |
root |
1.4 |
|
740 |
root |
1.22 |
print "trouble tickets:\n" , $f1->recv, "\n"; |
741 |
root |
1.4 |
print "trouble ticket #1736:\n", $f2->recv, "\n"; |
742 |
root |
1.22 |
print "kernel release info: " , $f3->recv, "\n"; |
743 |
root |
1.4 |
|
744 |
|
|
It doesn't look like it, but in fact all three requests run in |
745 |
root |
1.9 |
parallel. The code waits for the first finger request to finish first, but |
746 |
root |
1.11 |
that doesn't keep it from executing them parallel: when the first C<recv> |
747 |
|
|
call sees that the data isn't ready yet, it serves events for all three |
748 |
|
|
requests automatically, until the first request has finished. |
749 |
|
|
|
750 |
|
|
The second C<recv> call might either find the data is already there, or it |
751 |
|
|
will continue handling events until that is the case, and so on. |
752 |
root |
1.9 |
|
753 |
|
|
By taking advantage of network latencies, which allows us to serve other |
754 |
|
|
requests and events while we wait for an event on one socket, the overall |
755 |
root |
1.11 |
time to do these three requests will be greatly reduced, typically all |
756 |
root |
1.28 |
three are done in the same time as the slowest of the three requests. |
757 |
root |
1.5 |
|
758 |
|
|
By the way, you do not actually have to wait in the C<recv> method on an |
759 |
root |
1.11 |
AnyEvent condition variable - after all, waiting is evil - you can also |
760 |
|
|
register a callback: |
761 |
root |
1.5 |
|
762 |
root |
1.28 |
$f1->cb (sub { |
763 |
root |
1.5 |
my $response = shift->recv; |
764 |
|
|
# ... |
765 |
|
|
}); |
766 |
|
|
|
767 |
root |
1.28 |
The callback will be invoked only when C<send> is called. In fact, |
768 |
root |
1.5 |
instead of returning a condition variable you could also pass a third |
769 |
|
|
parameter to your finger function, the callback to invoke with the |
770 |
|
|
response: |
771 |
|
|
|
772 |
|
|
sub finger($$$) { |
773 |
|
|
my ($user, $host, $cb) = @_; |
774 |
|
|
|
775 |
root |
1.11 |
How you implement it is a matter of taste - if you expect your function to |
776 |
|
|
be used mainly in an event-based program you would normally prefer to pass |
777 |
|
|
a callback directly. If you write a module and expect your users to use |
778 |
|
|
it "synchronously" often (for example, a simple http-get script would not |
779 |
|
|
really care much for events), then you would use a condition variable and |
780 |
root |
1.22 |
tell them "simply C<< ->recv >> the data". |
781 |
root |
1.4 |
|
782 |
root |
1.11 |
=head3 Problems with the implementation and how to fix them |
783 |
root |
1.4 |
|
784 |
|
|
To make this example more real-world-ready, we would not only implement |
785 |
root |
1.22 |
some write buffering (for the paranoid, or maybe denial-of-service aware |
786 |
|
|
security expert), but we would also have to handle timeouts and maybe |
787 |
|
|
protocol errors. |
788 |
root |
1.4 |
|
789 |
root |
1.11 |
Doing this quickly gets unwieldy, which is why we introduce |
790 |
|
|
L<AnyEvent::Handle> in the next section, which takes care of all these |
791 |
root |
1.28 |
details for you and lets you concentrate on the actual protocol. |
792 |
root |
1.11 |
|
793 |
|
|
|
794 |
|
|
=head2 Implementing simple HTTP and HTTPS GET requests with AnyEvent::Handle |
795 |
|
|
|
796 |
root |
1.22 |
The L<AnyEvent::Handle> module has been hyped quite a bit in this document |
797 |
|
|
so far, so let's see what it really offers. |
798 |
root |
1.11 |
|
799 |
|
|
As finger is such a simple protocol, let's try something slightly more |
800 |
|
|
complicated: HTTP/1.0. |
801 |
|
|
|
802 |
|
|
An HTTP GET request works by sending a single request line that indicates |
803 |
|
|
what you want the server to do and the URI you want to act it on, followed |
804 |
|
|
by as many "header" lines (C<Header: data>, same as e-mail headers) as |
805 |
root |
1.28 |
required for the request, followed by an empty line. |
806 |
root |
1.11 |
|
807 |
|
|
The response is formatted very similarly, first a line with the response |
808 |
|
|
status, then again as many header lines as required, then an empty line, |
809 |
|
|
followed by any data that the server might send. |
810 |
|
|
|
811 |
|
|
Again, let's try it out with C<telnet> (I condensed the output a bit - if |
812 |
|
|
you want to see the full response, do it yourself). |
813 |
|
|
|
814 |
|
|
# telnet www.google.com 80 |
815 |
|
|
Trying 209.85.135.99... |
816 |
|
|
Connected to www.google.com (209.85.135.99). |
817 |
|
|
Escape character is '^]'. |
818 |
|
|
GET /test HTTP/1.0 |
819 |
|
|
|
820 |
|
|
HTTP/1.0 404 Not Found |
821 |
|
|
Date: Mon, 02 Jun 2008 07:05:54 GMT |
822 |
|
|
Content-Type: text/html; charset=UTF-8 |
823 |
|
|
|
824 |
|
|
<html><head> |
825 |
|
|
[...] |
826 |
|
|
Connection closed by foreign host. |
827 |
|
|
|
828 |
|
|
The C<GET ...> and the empty line were entered manually, the rest of the |
829 |
root |
1.28 |
telnet output is google's response, in this case a C<404 not found> one. |
830 |
root |
1.11 |
|
831 |
|
|
So, here is how you would do it with C<AnyEvent::Handle>: |
832 |
|
|
|
833 |
root |
1.12 |
sub http_get { |
834 |
|
|
my ($host, $uri, $cb) = @_; |
835 |
|
|
|
836 |
root |
1.24 |
# store results here |
837 |
|
|
my ($response, $header, $body); |
838 |
|
|
|
839 |
|
|
my $handle; $handle = new AnyEvent::Handle |
840 |
|
|
connect => [$host => 'http'], |
841 |
|
|
on_error => sub { |
842 |
|
|
$cb->("HTTP/1.0 500 $!"); |
843 |
|
|
$handle->destroy; # explicitly destroy handle |
844 |
|
|
}, |
845 |
|
|
on_eof => sub { |
846 |
|
|
$cb->($response, $header, $body); |
847 |
|
|
$handle->destroy; # explicitly destroy handle |
848 |
|
|
}; |
849 |
root |
1.12 |
|
850 |
root |
1.24 |
$handle->push_write ("GET $uri HTTP/1.0\015\012\015\012"); |
851 |
root |
1.12 |
|
852 |
root |
1.24 |
# now fetch response status line |
853 |
|
|
$handle->push_read (line => sub { |
854 |
|
|
my ($handle, $line) = @_; |
855 |
|
|
$response = $line; |
856 |
|
|
}); |
857 |
root |
1.12 |
|
858 |
root |
1.24 |
# then the headers |
859 |
|
|
$handle->push_read (line => "\015\012\015\012", sub { |
860 |
|
|
my ($handle, $line) = @_; |
861 |
|
|
$header = $line; |
862 |
|
|
}); |
863 |
root |
1.12 |
|
864 |
root |
1.24 |
# and finally handle any remaining data as body |
865 |
|
|
$handle->on_read (sub { |
866 |
|
|
$body .= $_[0]->rbuf; |
867 |
|
|
$_[0]->rbuf = ""; |
868 |
|
|
}); |
869 |
root |
1.12 |
} |
870 |
root |
1.11 |
|
871 |
|
|
And now let's go through it step by step. First, as usual, the overall |
872 |
|
|
C<http_get> function structure: |
873 |
|
|
|
874 |
|
|
sub http_get { |
875 |
|
|
my ($host, $uri, $cb) = @_; |
876 |
|
|
|
877 |
root |
1.24 |
# store results here |
878 |
|
|
my ($response, $header, $body); |
879 |
|
|
|
880 |
|
|
my $handle; $handle = new AnyEvent::Handle |
881 |
|
|
... create handle object |
882 |
|
|
|
883 |
|
|
... push data to write |
884 |
|
|
|
885 |
|
|
... push what to expect to read queue |
886 |
root |
1.11 |
} |
887 |
|
|
|
888 |
|
|
Unlike in the finger example, this time the caller has to pass a callback |
889 |
|
|
to C<http_get>. Also, instead of passing a URL as one would expect, the |
890 |
|
|
caller has to provide the hostname and URI - normally you would use the |
891 |
|
|
C<URI> module to parse a URL and separate it into those parts, but that is |
892 |
|
|
left to the inspired reader :) |
893 |
|
|
|
894 |
root |
1.28 |
Since everything else is left to the caller, all C<http_get> does is |
895 |
root |
1.24 |
initiate the connection by creating the AnyEvent::Handle object (which |
896 |
root |
1.28 |
calls C<tcp_connect> for us) and leave everything else to its callback. |
897 |
root |
1.24 |
|
898 |
|
|
The handle object is created, unsurprisingly, by calling the C<new> |
899 |
|
|
method of L<AnyEvent::Handle>: |
900 |
root |
1.11 |
|
901 |
root |
1.24 |
my $handle; $handle = new AnyEvent::Handle |
902 |
|
|
connect => [$host => 'http'], |
903 |
|
|
on_error => sub { |
904 |
|
|
$cb->("HTTP/1.0 500 $!"); |
905 |
|
|
$handle->destroy; # explicitly destroy handle |
906 |
|
|
}, |
907 |
|
|
on_eof => sub { |
908 |
|
|
$cb->($response, $header, $body); |
909 |
|
|
$handle->destroy; # explicitly destroy handle |
910 |
|
|
}; |
911 |
root |
1.11 |
|
912 |
root |
1.24 |
The C<connect> argument tells AnyEvent::Handle to call C<tcp_connect> for |
913 |
|
|
the specified host and service/port. |
914 |
root |
1.11 |
|
915 |
root |
1.24 |
The C<on_error> callback will be called on any unexpected error, such as a |
916 |
root |
1.28 |
refused connection, or unexpected end-of-file while reading headers. |
917 |
root |
1.11 |
|
918 |
|
|
Instead of having an extra mechanism to signal errors, connection errors |
919 |
|
|
are signalled by crafting a special "response status line", like this: |
920 |
|
|
|
921 |
|
|
HTTP/1.0 500 Connection refused |
922 |
|
|
|
923 |
|
|
This means the caller cannot distinguish (easily) between |
924 |
|
|
locally-generated errors and server errors, but it simplifies error |
925 |
|
|
handling for the caller a lot. |
926 |
|
|
|
927 |
root |
1.24 |
The error callback also destroys the handle explicitly, because we are not |
928 |
|
|
interested in continuing after any errors. In AnyEvent::Handle callbacks |
929 |
|
|
you have to call C<destroy> explicitly to destroy a handle. Outside of |
930 |
root |
1.28 |
those callbacks you can just forget the object reference and it will be |
931 |
root |
1.24 |
automatically cleaned up. |
932 |
|
|
|
933 |
root |
1.28 |
Last but not least, we set an C<on_eof> callback that is called when the |
934 |
root |
1.24 |
other side indicates it has stopped writing data, which we will use to |
935 |
|
|
gracefully shut down the handle and report the results. This callback is |
936 |
root |
1.28 |
only called when the read queue is empty - if the read queue expects |
937 |
|
|
some data and the handle gets an EOF from the other side this will be an |
938 |
|
|
error - after all, you did expect more to come. |
939 |
root |
1.11 |
|
940 |
root |
1.24 |
If you wanted to write a server using AnyEvent::Handle, you would use |
941 |
|
|
C<tcp_accept> and then create the AnyEvent::Handle with the C<fh> |
942 |
root |
1.11 |
argument. |
943 |
|
|
|
944 |
|
|
=head3 The write queue |
945 |
|
|
|
946 |
|
|
The next line sends the actual request: |
947 |
|
|
|
948 |
root |
1.24 |
$handle->push_write ("GET $uri HTTP/1.0\015\012\015\012"); |
949 |
root |
1.11 |
|
950 |
|
|
No headers will be sent (this is fine for simple requests), so the whole |
951 |
|
|
request is just a single line followed by an empty line to signal the end |
952 |
|
|
of the headers to the server. |
953 |
|
|
|
954 |
|
|
The more interesting question is why the method is called C<push_write> |
955 |
|
|
and not just write. The reason is that you can I<always> add some write |
956 |
|
|
data without blocking, and to do this, AnyEvent::Handle needs some write |
957 |
root |
1.28 |
queue internally - and C<push_write> pushes some data onto the end of |
958 |
|
|
that queue, just like Perl's C<push> pushes data onto the end of an |
959 |
root |
1.22 |
array. |
960 |
root |
1.11 |
|
961 |
|
|
The deeper reason is that at some point in the future, there might |
962 |
|
|
be C<unshift_write> as well, and in any case, we will shortly meet |
963 |
root |
1.22 |
C<push_read> and C<unshift_read>, and it's usually easiest to remember if |
964 |
root |
1.24 |
all those functions have some symmetry in their name. So C<push> is used |
965 |
|
|
as the opposite of C<unshift> in AnyEvent::Handle, not as the opposite of |
966 |
|
|
C<pull> - just like in Perl. |
967 |
|
|
|
968 |
|
|
Note that we call C<push_write> right after creating the AnyEvent::Handle |
969 |
|
|
object, before it has had time to actually connect to the server. This is |
970 |
root |
1.28 |
fine, pushing the read and write requests will queue them in the handle |
971 |
|
|
object until the connection has been established. Alternatively, we |
972 |
root |
1.24 |
could do this "on demand" in the C<on_connect> callback. |
973 |
root |
1.11 |
|
974 |
root |
1.28 |
If C<push_write> is called with more than one argument, then you can do |
975 |
|
|
I<formatted> I/O. For example, this would JSON-encode your data before |
976 |
|
|
pushing it to the write queue: |
977 |
root |
1.11 |
|
978 |
|
|
$handle->push_write (json => [1, 2, 3]); |
979 |
|
|
|
980 |
root |
1.28 |
This pretty much summarises the write queue, there is little else to it. |
981 |
root |
1.11 |
|
982 |
root |
1.22 |
Reading the response is far more interesting, because it involves the more |
983 |
|
|
powerful and complex I<read queue>: |
984 |
root |
1.11 |
|
985 |
|
|
=head3 The read queue |
986 |
|
|
|
987 |
root |
1.22 |
The response consists of three parts: a single line with the response |
988 |
|
|
status, a single paragraph of headers ended by an empty line, and the |
989 |
root |
1.28 |
request body, which is the remaining data on the connection. |
990 |
root |
1.11 |
|
991 |
|
|
For the first two, we push two read requests onto the read queue: |
992 |
|
|
|
993 |
root |
1.24 |
# now fetch response status line |
994 |
|
|
$handle->push_read (line => sub { |
995 |
|
|
my ($handle, $line) = @_; |
996 |
|
|
$response = $line; |
997 |
|
|
}); |
998 |
root |
1.11 |
|
999 |
root |
1.24 |
# then the headers |
1000 |
|
|
$handle->push_read (line => "\015\012\015\012", sub { |
1001 |
|
|
my ($handle, $line) = @_; |
1002 |
|
|
$header = $line; |
1003 |
|
|
}); |
1004 |
root |
1.11 |
|
1005 |
root |
1.28 |
While one can just push a single callback to parse all the data on the |
1006 |
|
|
queue, formatted I/O really comes to our aid here, since there is a |
1007 |
|
|
ready-made "read line" read type. The first read expects a single line, |
1008 |
|
|
ended by C<\015\012> (the standard end-of-line marker in internet |
1009 |
root |
1.22 |
protocols). |
1010 |
root |
1.11 |
|
1011 |
|
|
The second "line" is actually a single paragraph - instead of reading it |
1012 |
|
|
line by line we tell C<push_read> that the end-of-line marker is really |
1013 |
|
|
C<\015\012\015\012>, which is an empty line. The result is that the whole |
1014 |
|
|
header paragraph will be treated as a single line and read. The word |
1015 |
|
|
"line" is interpreted very freely, much like Perl itself does it. |
1016 |
|
|
|
1017 |
|
|
Note that push read requests are pushed immediately after creating the |
1018 |
|
|
handle object - since AnyEvent::Handle provides a queue we can push as |
1019 |
|
|
many requests as we want, and AnyEvent::Handle will handle them in order. |
1020 |
|
|
|
1021 |
|
|
There is, however, no read type for "the remaining data". For that, we |
1022 |
|
|
install our own C<on_read> callback: |
1023 |
|
|
|
1024 |
root |
1.24 |
# and finally handle any remaining data as body |
1025 |
|
|
$handle->on_read (sub { |
1026 |
|
|
$body .= $_[0]->rbuf; |
1027 |
|
|
$_[0]->rbuf = ""; |
1028 |
|
|
}); |
1029 |
root |
1.11 |
|
1030 |
|
|
This callback is invoked every time data arrives and the read queue is |
1031 |
|
|
empty - which in this example will only be the case when both response and |
1032 |
root |
1.12 |
header have been read. The C<on_read> callback could actually have been |
1033 |
|
|
specified when constructing the object, but doing it this way preserves |
1034 |
|
|
logical ordering. |
1035 |
root |
1.1 |
|
1036 |
root |
1.28 |
The read callback adds the current read buffer to its C<$body> |
1037 |
root |
1.22 |
variable and, most importantly, I<empties> the buffer by assigning the |
1038 |
|
|
empty string to it. |
1039 |
root |
1.1 |
|
1040 |
root |
1.28 |
Given these instructions, AnyEvent::Handle will handle incoming data - |
1041 |
|
|
if all goes well, the callback will be invoked with the response data; |
1042 |
|
|
if not, it will get an error. |
1043 |
root |
1.1 |
|
1044 |
root |
1.22 |
In general, you can implement pipelining (a semi-advanced feature of many |
1045 |
root |
1.28 |
protocols) very easily with AnyEvent::Handle: If you have a protocol |
1046 |
|
|
with a request/response structure, your request methods/functions will |
1047 |
|
|
all look like this (simplified): |
1048 |
root |
1.13 |
|
1049 |
|
|
sub request { |
1050 |
|
|
|
1051 |
|
|
# send the request to the server |
1052 |
|
|
$handle->push_write (...); |
1053 |
|
|
|
1054 |
|
|
# push some response handlers |
1055 |
|
|
$handle->push_read (...); |
1056 |
|
|
} |
1057 |
|
|
|
1058 |
root |
1.22 |
This means you can queue as many requests as you want, and while |
1059 |
|
|
AnyEvent::Handle goes through its read queue to handle the response data, |
1060 |
|
|
the other side can work on the next request - queueing the request just |
1061 |
|
|
appends some data to the write queue and installs a handler to be called |
1062 |
|
|
later. |
1063 |
|
|
|
1064 |
|
|
You might ask yourself how to handle decisions you can only make I<after> |
1065 |
|
|
you have received some data (such as handling a short error response or a |
1066 |
|
|
long and differently-formatted response). The answer to this problem is |
1067 |
|
|
C<unshift_read>, which we will introduce together with an example in the |
1068 |
|
|
coming sections. |
1069 |
root |
1.1 |
|
1070 |
root |
1.22 |
=head3 Using C<http_get> |
1071 |
|
|
|
1072 |
|
|
Finally, here is how you would use C<http_get>: |
1073 |
root |
1.1 |
|
1074 |
root |
1.12 |
http_get "www.google.com", "/", sub { |
1075 |
|
|
my ($response, $header, $body) = @_; |
1076 |
root |
1.1 |
|
1077 |
root |
1.12 |
print |
1078 |
|
|
$response, "\n", |
1079 |
|
|
$body; |
1080 |
|
|
}; |
1081 |
root |
1.1 |
|
1082 |
root |
1.12 |
And of course, you can run as many of these requests in parallel as you |
1083 |
|
|
want (and your memory supports). |
1084 |
root |
1.1 |
|
1085 |
root |
1.13 |
=head3 HTTPS |
1086 |
|
|
|
1087 |
|
|
Now, as promised, let's implement the same thing for HTTPS, or more |
1088 |
|
|
correctly, let's change our C<http_get> function into a function that |
1089 |
|
|
speaks HTTPS instead. |
1090 |
|
|
|
1091 |
root |
1.28 |
HTTPS is a standard TLS connection (B<T>ransport B<L>ayer |
1092 |
root |
1.13 |
B<S>ecurity is the official name for what most people refer to as C<SSL>) |
1093 |
root |
1.22 |
that contains standard HTTP protocol exchanges. The only other difference |
1094 |
|
|
to HTTP is that by default it uses port C<443> instead of port C<80>. |
1095 |
root |
1.13 |
|
1096 |
root |
1.22 |
To implement these two differences we need two tiny changes, first, in the |
1097 |
root |
1.24 |
C<connect> parameter, we replace C<http> by C<https> to connect to the |
1098 |
|
|
https port: |
1099 |
root |
1.13 |
|
1100 |
root |
1.24 |
connect => [$host => 'https'], |
1101 |
root |
1.13 |
|
1102 |
|
|
The other change deals with TLS, which is something L<AnyEvent::Handle> |
1103 |
root |
1.28 |
does for us if the L<Net::SSLeay> module is available. To enable TLS |
1104 |
|
|
with L<AnyEvent::Handle>, we pass an additional C<tls> parameter |
1105 |
|
|
to the call to C<AnyEvent::Handle::new>: |
1106 |
root |
1.13 |
|
1107 |
|
|
tls => "connect", |
1108 |
|
|
|
1109 |
|
|
Specifying C<tls> enables TLS, and the argument specifies whether |
1110 |
|
|
AnyEvent::Handle is the server side ("accept") or the client side |
1111 |
|
|
("connect") for the TLS connection, as unlike TCP, there is a clear |
1112 |
|
|
server/client relationship in TLS. |
1113 |
|
|
|
1114 |
root |
1.14 |
That's all. |
1115 |
|
|
|
1116 |
root |
1.22 |
Of course, all this should be handled transparently by C<http_get> |
1117 |
|
|
after parsing the URL. If you need this, see the part about exercising |
1118 |
|
|
your inspiration earlier in this document. You could also use the |
1119 |
|
|
L<AnyEvent::HTTP> module from CPAN, which implements all this and works |
1120 |
root |
1.28 |
around a lot of quirks for you too. |
1121 |
root |
1.13 |
|
1122 |
root |
1.12 |
=head3 The read queue - revisited |
1123 |
root |
1.1 |
|
1124 |
root |
1.13 |
HTTP always uses the same structure in its responses, but many protocols |
1125 |
root |
1.22 |
require parsing responses differently depending on the response itself. |
1126 |
root |
1.13 |
|
1127 |
|
|
For example, in SMTP, you normally get a single response line: |
1128 |
|
|
|
1129 |
|
|
220 mail.example.net Neverusesendmail 8.8.8 <mailme@example.net> |
1130 |
|
|
|
1131 |
|
|
But SMTP also supports multi-line responses: |
1132 |
|
|
|
1133 |
|
|
220-mail.example.net Neverusesendmail 8.8.8 <mailme@example.net> |
1134 |
|
|
220-hey guys |
1135 |
|
|
220 my response is longer than yours |
1136 |
|
|
|
1137 |
root |
1.28 |
To handle this, we need C<unshift_read>. As the name (we hope) implies, |
1138 |
root |
1.22 |
C<unshift_read> will not append your read request to the end of the read |
1139 |
root |
1.28 |
queue, but will prepend it to the queue instead. |
1140 |
root |
1.13 |
|
1141 |
root |
1.22 |
This is useful in the situation above: Just push your response-line read |
1142 |
root |
1.13 |
request when sending the SMTP command, and when handling it, you look at |
1143 |
root |
1.22 |
the line to see if more is to come, and C<unshift_read> another reader |
1144 |
|
|
callback if required, like this: |
1145 |
root |
1.13 |
|
1146 |
|
|
my $response; # response lines end up in here |
1147 |
|
|
|
1148 |
|
|
my $read_response; $read_response = sub { |
1149 |
|
|
my ($handle, $line) = @_; |
1150 |
|
|
|
1151 |
|
|
$response .= "$line\n"; |
1152 |
|
|
|
1153 |
|
|
# check for continuation lines ("-" as 4th character") |
1154 |
|
|
if ($line =~ /^...-/) { |
1155 |
|
|
# if yes, then unshift another line read |
1156 |
|
|
$handle->unshift_read (line => $read_response); |
1157 |
|
|
|
1158 |
|
|
} else { |
1159 |
|
|
# otherwise we are done |
1160 |
|
|
|
1161 |
|
|
# free callback |
1162 |
|
|
undef $read_response; |
1163 |
|
|
|
1164 |
|
|
print "we are don reading: $response\n"; |
1165 |
|
|
} |
1166 |
|
|
}; |
1167 |
|
|
|
1168 |
|
|
$handle->push_read (line => $read_response); |
1169 |
root |
1.1 |
|
1170 |
root |
1.13 |
This recipe can be used for all similar parsing problems, for example in |
1171 |
|
|
NNTP, the response code to some commands indicates that more data will be |
1172 |
root |
1.14 |
sent: |
1173 |
|
|
|
1174 |
|
|
$handle->push_write ("article 42"); |
1175 |
|
|
|
1176 |
|
|
# read response line |
1177 |
|
|
$handle->push_read (line => sub { |
1178 |
|
|
my ($handle, $status) = @_; |
1179 |
|
|
|
1180 |
|
|
# article data following? |
1181 |
|
|
if ($status =~ /^2/) { |
1182 |
|
|
# yes, read article body |
1183 |
|
|
|
1184 |
|
|
$handle->unshift_read (line => "\012.\015\012", sub { |
1185 |
|
|
my ($handle, $body) = @_; |
1186 |
|
|
|
1187 |
|
|
$finish->($status, $body); |
1188 |
|
|
}); |
1189 |
|
|
|
1190 |
|
|
} else { |
1191 |
|
|
# some error occured, no article data |
1192 |
|
|
|
1193 |
|
|
$finish->($status); |
1194 |
|
|
} |
1195 |
|
|
} |
1196 |
|
|
|
1197 |
|
|
=head3 Your own read queue handler |
1198 |
|
|
|
1199 |
root |
1.28 |
Sometimes your protocol doesn't play nice, and uses lines or chunks of |
1200 |
|
|
data not formatted in a way handled out of the box by AnyEvent::Handle. |
1201 |
|
|
In this case you have to implement your own read parser. |
1202 |
root |
1.14 |
|
1203 |
|
|
To make up a contorted example, imagine you are looking for an even |
1204 |
|
|
number of characters followed by a colon (":"). Also imagine that |
1205 |
root |
1.28 |
AnyEvent::Handle has no C<regex> read type which could be used, so you'd |
1206 |
|
|
have to do it manually. |
1207 |
root |
1.14 |
|
1208 |
root |
1.22 |
To implement a read handler for this, you would C<push_read> (or |
1209 |
root |
1.28 |
C<unshift_read>) a single code reference. |
1210 |
root |
1.14 |
|
1211 |
|
|
This code reference will then be called each time there is (new) data |
1212 |
root |
1.22 |
available in the read buffer, and is expected to either successfully |
1213 |
|
|
eat/consume some of that data (and return true) or to return false to |
1214 |
|
|
indicate that it wants to be called again. |
1215 |
|
|
|
1216 |
|
|
If the code reference returns true, then it will be removed from the |
1217 |
|
|
read queue (because it has parsed/consumed whatever it was supposed to |
1218 |
|
|
consume), otherwise it stays in the front of it. |
1219 |
root |
1.14 |
|
1220 |
|
|
The example above could be coded like this: |
1221 |
|
|
|
1222 |
|
|
$handle->push_read (sub { |
1223 |
|
|
my ($handle) = @_; |
1224 |
|
|
|
1225 |
|
|
# check for even number of characters + ":" |
1226 |
|
|
# and remove the data if a match is found. |
1227 |
|
|
# if not, return false (actually nothing) |
1228 |
|
|
|
1229 |
|
|
$handle->{rbuf} =~ s/^( (?:..)* ) ://x |
1230 |
|
|
or return; |
1231 |
|
|
|
1232 |
|
|
# we got some data in $1, pass it to whoever wants it |
1233 |
|
|
$finish->($1); |
1234 |
|
|
|
1235 |
|
|
# and return true to indicate we are done |
1236 |
|
|
1 |
1237 |
|
|
}); |
1238 |
|
|
|
1239 |
root |
1.31 |
|
1240 |
|
|
=head1 Debugging aids |
1241 |
|
|
|
1242 |
|
|
Now that you have seen how to use AnyEvent, here's what to use when you |
1243 |
|
|
don't use it correctly, or simply hit a bug somewhere and want to debug |
1244 |
|
|
it: |
1245 |
|
|
|
1246 |
|
|
=over 4 |
1247 |
|
|
|
1248 |
|
|
=item Enable strict argument checking during development |
1249 |
|
|
|
1250 |
|
|
AnyEvent does not, by default, do any argument checking. This can lead to |
1251 |
|
|
strange and unexpected results especially if you are just trying to find |
1252 |
|
|
your way with AnyEvent. |
1253 |
|
|
|
1254 |
|
|
AnyEvent supports a special "strict" mode - off by default - which does |
1255 |
|
|
very strict argument checking, at the expense of slowing down your |
1256 |
|
|
program. During development, however, this mode is very useful because it |
1257 |
|
|
quickly catches the msot common errors. |
1258 |
|
|
|
1259 |
|
|
You can enable this strict mode either by having an environment variable |
1260 |
|
|
C<AE_STRICT> with a true value in your environment: |
1261 |
|
|
|
1262 |
|
|
AE_STRICT=1 perl myprog |
1263 |
|
|
|
1264 |
|
|
Or you can write C<use AnyEvent::Strict> in your program, which has the |
1265 |
|
|
same effect (do not do this in production, however). |
1266 |
|
|
|
1267 |
|
|
=item Increase verbosity, configure logging |
1268 |
|
|
|
1269 |
|
|
AnyEvent, by default, only logs critical messages. If something doesn't |
1270 |
|
|
work, maybe there was a warning about it that you didn't see because it |
1271 |
|
|
was suppressed. |
1272 |
|
|
|
1273 |
|
|
So during development it is recommended to push up the logging level to at |
1274 |
|
|
least warn level (C<5>): |
1275 |
|
|
|
1276 |
|
|
AE_VERBOSE=5 perl myprog |
1277 |
|
|
|
1278 |
|
|
Other levels that might be helpful are debug (C<8>) or even trace (C<9>). |
1279 |
|
|
|
1280 |
|
|
AnyEvent's logging is quite versatile - the L<AnyEvent::Log> manpage has |
1281 |
|
|
all the details. |
1282 |
|
|
|
1283 |
|
|
=item Watcher wrapping, tracing, the shell |
1284 |
|
|
|
1285 |
|
|
For even more debugging, you can enable watcher wrapping: |
1286 |
|
|
|
1287 |
|
|
AE_DEBUG_WRAP=2 perl myprog |
1288 |
|
|
|
1289 |
|
|
This will have the effect of wrapping every watcher into a special object |
1290 |
|
|
that stores a backtrace of when it was created, stores a backtrace |
1291 |
|
|
when an exception occurs during watcher execution, and stores a lot |
1292 |
|
|
of other information. If that slows down your program too much, then |
1293 |
|
|
C<AE_DEBUG_WRAP=1> avoids the costly backtraces. |
1294 |
|
|
|
1295 |
|
|
Here is an example of what of information is stored: |
1296 |
|
|
|
1297 |
|
|
59148536 DC::DB:472(Server::run)>io>DC::DB::Server::fh_read |
1298 |
|
|
type: io watcher |
1299 |
|
|
args: poll r fh GLOB(0x35283f0) |
1300 |
|
|
created: 2011-09-01 23:13:46.597336 +0200 (1314911626.59734) |
1301 |
|
|
file: ./blib/lib/Deliantra/Client/private/DC/DB.pm |
1302 |
|
|
line: 472 |
1303 |
|
|
subname: DC::DB::Server::run |
1304 |
|
|
context: |
1305 |
|
|
tracing: enabled |
1306 |
|
|
cb: CODE(0x2d1fb98) (DC::DB::Server::fh_read) |
1307 |
|
|
invoked: 0 times |
1308 |
|
|
created |
1309 |
|
|
(eval 25) line 6 AnyEvent::Debug::Wrap::__ANON__('AnyEvent','fh',GLOB(0x35283f0),'poll','r','cb',CODE(0x2d1fb98)=DC::DB::Server::fh_read) |
1310 |
|
|
DC::DB line 472 AE::io(GLOB(0x35283f0),'0',CODE(0x2d1fb98)=DC::DB::Server::fh_read) |
1311 |
|
|
bin/deliantra line 2776 DC::DB::Server::run() |
1312 |
|
|
bin/deliantra line 2941 main::main() |
1313 |
|
|
|
1314 |
|
|
There are many ways to get at this data - see the L<AnyEvent::Debug> and |
1315 |
|
|
L<AnyEvent::Log> manpages for more details. |
1316 |
|
|
|
1317 |
|
|
The most interesting and interactive way is to create a debug shell, for |
1318 |
|
|
example by setting C<AE_DEBUG_SHELL>: |
1319 |
|
|
|
1320 |
|
|
AE_DEBUG_WRAP=2 AE_DEBUG_SHELL=$HOME/myshell ./myprog |
1321 |
|
|
|
1322 |
|
|
# while myprog is running: |
1323 |
|
|
socat readline $HOME/myshell |
1324 |
|
|
|
1325 |
|
|
Note that anybody who can access F<$HOME/myshell> can make your program |
1326 |
|
|
do anything he or she wants, so if you are not the only user on your |
1327 |
|
|
machine, better put it into a secure location (F<$HOME> might not be |
1328 |
|
|
secure enough). |
1329 |
|
|
|
1330 |
|
|
If you don't have C<socat> (a shame!) and care even less about security, |
1331 |
|
|
you can also use TCP and C<telnet>: |
1332 |
|
|
|
1333 |
|
|
AE_DEBUG_WRAP=2 AE_DEBUG_SHELL=127.0.0.1:1234 ./myprog |
1334 |
|
|
|
1335 |
|
|
telnet 127.0.0.1 1234 |
1336 |
|
|
|
1337 |
|
|
The debug shell can enable and disable tracing of watcher invocations, |
1338 |
|
|
can display the trace output, give you a list of watchers and lets you |
1339 |
|
|
investigate watchers in detail. |
1340 |
|
|
|
1341 |
|
|
=back |
1342 |
|
|
|
1343 |
root |
1.22 |
This concludes our little tutorial. |
1344 |
|
|
|
1345 |
root |
1.31 |
|
1346 |
root |
1.22 |
=head1 Where to go from here? |
1347 |
|
|
|
1348 |
root |
1.23 |
This introduction should have explained the key concepts of L<AnyEvent> |
1349 |
|
|
- event watchers and condition variables, L<AnyEvent::Socket> - basic |
1350 |
|
|
networking utilities, and L<AnyEvent::Handle> - a nice wrapper around |
1351 |
root |
1.28 |
sockets. |
1352 |
root |
1.22 |
|
1353 |
|
|
You could either start coding stuff right away, look at those manual |
1354 |
|
|
pages for the gory details, or roam CPAN for other AnyEvent modules (such |
1355 |
|
|
as L<AnyEvent::IRC> or L<AnyEvent::HTTP>) to see more code examples (or |
1356 |
|
|
simply to use them). |
1357 |
|
|
|
1358 |
|
|
If you need a protocol that doesn't have an implementation using AnyEvent, |
1359 |
|
|
remember that you can mix AnyEvent with one other event framework, such as |
1360 |
|
|
L<POE>, so you can always use AnyEvent for your own tasks plus modules of |
1361 |
|
|
one other event framework to fill any gaps. |
1362 |
|
|
|
1363 |
|
|
And last not least, you could also look at L<Coro>, especially |
1364 |
|
|
L<Coro::AnyEvent>, to see how you can turn event-based programming from |
1365 |
|
|
callback style back to the usual imperative style (also called "inversion |
1366 |
|
|
of control" - AnyEvent calls I<you>, but Coro lets I<you> call AnyEvent). |
1367 |
root |
1.1 |
|
1368 |
root |
1.15 |
=head1 Authors |
1369 |
root |
1.6 |
|
1370 |
|
|
Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. |
1371 |
|
|
|