ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.102 by root, Sun Apr 27 21:16:26 2008 UTC vs.
Revision 1.160 by root, Sun Jun 22 12:17:47 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 15 my $w = AnyEvent->timer (after => $seconds, cb => sub {
16 ... 16 ...
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 19 my $w = AnyEvent->condvar; # stores whether a condition was flagged
20 $w->send; # wake up current and all future recv's
20 $w->wait; # enters "main loop" till $condvar gets ->broadcast 21 $w->recv; # enters "main loop" till $condvar gets ->send
21 $w->broadcast; # wake up current and all future wait's 22
23=head1 INTRODUCTION/TUTORIAL
24
25This manpage is mainly a reference manual. If you are interested
26in a tutorial or some gentle introduction, have a look at the
27L<AnyEvent::Intro> manpage.
22 28
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 29=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 30
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 31Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 32nowadays. So what is different about AnyEvent?
48isn't itself. What's worse, all the potential users of your module are 54isn't itself. What's worse, all the potential users of your module are
49I<also> forced to use the same event loop you use. 55I<also> forced to use the same event loop you use.
50 56
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 57AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 58fine. AnyEvent + Tk works fine etc. etc. but none of these work together
53with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if 59with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
54your module uses one of those, every user of your module has to use it, 60your module uses one of those, every user of your module has to use it,
55too. But if your module uses AnyEvent, it works transparently with all 61too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 62event models it supports (including stuff like POE and IO::Async, as long
57as those use one of the supported event loops. It is trivial to add new 63as those use one of the supported event loops. It is trivial to add new
58event loops to AnyEvent, too, so it is future-proof). 64event loops to AnyEvent, too, so it is future-proof).
59 65
60In addition to being free of having to use I<the one and only true event 66In addition to being free of having to use I<the one and only true event
61model>, AnyEvent also is free of bloat and policy: with POE or similar 67model>, AnyEvent also is free of bloat and policy: with POE or similar
62modules, you get an enourmous amount of code and strict rules you have to 68modules, you get an enormous amount of code and strict rules you have to
63follow. AnyEvent, on the other hand, is lean and up to the point, by only 69follow. AnyEvent, on the other hand, is lean and up to the point, by only
64offering the functionality that is necessary, in as thin as a wrapper as 70offering the functionality that is necessary, in as thin as a wrapper as
65technically possible. 71technically possible.
66 72
73Of course, AnyEvent comes with a big (and fully optional!) toolbox
74of useful functionality, such as an asynchronous DNS resolver, 100%
75non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
76such as Windows) and lots of real-world knowledge and workarounds for
77platform bugs and differences.
78
67Of course, if you want lots of policy (this can arguably be somewhat 79Now, if you I<do want> lots of policy (this can arguably be somewhat
68useful) and you want to force your users to use the one and only event 80useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 81model, you should I<not> use this module.
70 82
71=head1 DESCRIPTION 83=head1 DESCRIPTION
72 84
78The interface itself is vaguely similar, but not identical to the L<Event> 90The interface itself is vaguely similar, but not identical to the L<Event>
79module. 91module.
80 92
81During the first call of any watcher-creation method, the module tries 93During the first call of any watcher-creation method, the module tries
82to detect the currently loaded event loop by probing whether one of the 94to detect the currently loaded event loop by probing whether one of the
83following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 95following modules is already loaded: L<EV>,
84L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, 96L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
85L<POE>. The first one found is used. If none are found, the module tries 97L<POE>. The first one found is used. If none are found, the module tries
86to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl 98to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
87adaptor should always succeed) in the order given. The first one that can 99adaptor should always succeed) in the order given. The first one that can
88be successfully loaded will be used. If, after this, still none could be 100be successfully loaded will be used. If, after this, still none could be
102starts using it, all bets are off. Maybe you should tell their authors to 114starts using it, all bets are off. Maybe you should tell their authors to
103use AnyEvent so their modules work together with others seamlessly... 115use AnyEvent so their modules work together with others seamlessly...
104 116
105The pure-perl implementation of AnyEvent is called 117The pure-perl implementation of AnyEvent is called
106C<AnyEvent::Impl::Perl>. Like other event modules you can load it 118C<AnyEvent::Impl::Perl>. Like other event modules you can load it
107explicitly. 119explicitly and enjoy the high availability of that event loop :)
108 120
109=head1 WATCHERS 121=head1 WATCHERS
110 122
111AnyEvent has the central concept of a I<watcher>, which is an object that 123AnyEvent has the central concept of a I<watcher>, which is an object that
112stores relevant data for each kind of event you are waiting for, such as 124stores relevant data for each kind of event you are waiting for, such as
113the callback to call, the filehandle to watch, etc. 125the callback to call, the file handle to watch, etc.
114 126
115These watchers are normal Perl objects with normal Perl lifetime. After 127These watchers are normal Perl objects with normal Perl lifetime. After
116creating a watcher it will immediately "watch" for events and invoke the 128creating a watcher it will immediately "watch" for events and invoke the
117callback when the event occurs (of course, only when the event model 129callback when the event occurs (of course, only when the event model
118is in control). 130is in control).
126Many watchers either are used with "recursion" (repeating timers for 138Many watchers either are used with "recursion" (repeating timers for
127example), or need to refer to their watcher object in other ways. 139example), or need to refer to their watcher object in other ways.
128 140
129An any way to achieve that is this pattern: 141An any way to achieve that is this pattern:
130 142
131 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 143 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
132 # you can use $w here, for example to undef it 144 # you can use $w here, for example to undef it
133 undef $w; 145 undef $w;
134 }); 146 });
135 147
136Note that C<my $w; $w => combination. This is necessary because in Perl, 148Note that C<my $w; $w => combination. This is necessary because in Perl,
137my variables are only visible after the statement in which they are 149my variables are only visible after the statement in which they are
138declared. 150declared.
139 151
227timers. 239timers.
228 240
229AnyEvent always prefers relative timers, if available, matching the 241AnyEvent always prefers relative timers, if available, matching the
230AnyEvent API. 242AnyEvent API.
231 243
244AnyEvent has two additional methods that return the "current time":
245
246=over 4
247
248=item AnyEvent->time
249
250This returns the "current wallclock time" as a fractional number of
251seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
252return, and the result is guaranteed to be compatible with those).
253
254It progresses independently of any event loop processing, i.e. each call
255will check the system clock, which usually gets updated frequently.
256
257=item AnyEvent->now
258
259This also returns the "current wallclock time", but unlike C<time>, above,
260this value might change only once per event loop iteration, depending on
261the event loop (most return the same time as C<time>, above). This is the
262time that AnyEvent's timers get scheduled against.
263
264I<In almost all cases (in all cases if you don't care), this is the
265function to call when you want to know the current time.>
266
267This function is also often faster then C<< AnyEvent->time >>, and
268thus the preferred method if you want some timestamp (for example,
269L<AnyEvent::Handle> uses this to update it's activity timeouts).
270
271The rest of this section is only of relevance if you try to be very exact
272with your timing, you can skip it without bad conscience.
273
274For a practical example of when these times differ, consider L<Event::Lib>
275and L<EV> and the following set-up:
276
277The event loop is running and has just invoked one of your callback at
278time=500 (assume no other callbacks delay processing). In your callback,
279you wait a second by executing C<sleep 1> (blocking the process for a
280second) and then (at time=501) you create a relative timer that fires
281after three seconds.
282
283With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
284both return C<501>, because that is the current time, and the timer will
285be scheduled to fire at time=504 (C<501> + C<3>).
286
287With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
288time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
289last event processing phase started. With L<EV>, your timer gets scheduled
290to run at time=503 (C<500> + C<3>).
291
292In one sense, L<Event::Lib> is more exact, as it uses the current time
293regardless of any delays introduced by event processing. However, most
294callbacks do not expect large delays in processing, so this causes a
295higher drift (and a lot more system calls to get the current time).
296
297In another sense, L<EV> is more exact, as your timer will be scheduled at
298the same time, regardless of how long event processing actually took.
299
300In either case, if you care (and in most cases, you don't), then you
301can get whatever behaviour you want with any event loop, by taking the
302difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
303account.
304
305=back
306
232=head2 SIGNAL WATCHERS 307=head2 SIGNAL WATCHERS
233 308
234You can watch for signals using a signal watcher, C<signal> is the signal 309You can watch for signals using a signal watcher, C<signal> is the signal
235I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 310I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
236be invoked whenever a signal occurs. 311be invoked whenever a signal occurs.
237 312
238Although the callback might get passed parameters, their value and 313Although the callback might get passed parameters, their value and
239presence is undefined and you cannot rely on them. Portable AnyEvent 314presence is undefined and you cannot rely on them. Portable AnyEvent
240callbacks cannot use arguments passed to signal watcher callbacks. 315callbacks cannot use arguments passed to signal watcher callbacks.
241 316
242Multiple signal occurances can be clumped together into one callback 317Multiple signal occurrences can be clumped together into one callback
243invocation, and callback invocation will be synchronous. synchronous means 318invocation, and callback invocation will be synchronous. Synchronous means
244that it might take a while until the signal gets handled by the process, 319that it might take a while until the signal gets handled by the process,
245but it is guarenteed not to interrupt any other callbacks. 320but it is guaranteed not to interrupt any other callbacks.
246 321
247The main advantage of using these watchers is that you can share a signal 322The main advantage of using these watchers is that you can share a signal
248between multiple watchers. 323between multiple watchers.
249 324
250This watcher might use C<%SIG>, so programs overwriting those signals 325This watcher might use C<%SIG>, so programs overwriting those signals
277AnyEvent program, you I<have> to create at least one watcher before you 352AnyEvent program, you I<have> to create at least one watcher before you
278C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 353C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
279 354
280Example: fork a process and wait for it 355Example: fork a process and wait for it
281 356
282 my $done = AnyEvent->condvar; 357 my $done = AnyEvent->condvar;
283 358
284 AnyEvent::detect; # force event module to be initialised
285
286 my $pid = fork or exit 5; 359 my $pid = fork or exit 5;
287 360
288 my $w = AnyEvent->child ( 361 my $w = AnyEvent->child (
289 pid => $pid, 362 pid => $pid,
290 cb => sub { 363 cb => sub {
291 my ($pid, $status) = @_; 364 my ($pid, $status) = @_;
292 warn "pid $pid exited with status $status"; 365 warn "pid $pid exited with status $status";
293 $done->broadcast; 366 $done->send;
294 }, 367 },
295 ); 368 );
296 369
297 # do something else, then wait for process exit 370 # do something else, then wait for process exit
298 $done->wait; 371 $done->recv;
299 372
300=head2 CONDITION VARIABLES 373=head2 CONDITION VARIABLES
301 374
375If you are familiar with some event loops you will know that all of them
376require you to run some blocking "loop", "run" or similar function that
377will actively watch for new events and call your callbacks.
378
379AnyEvent is different, it expects somebody else to run the event loop and
380will only block when necessary (usually when told by the user).
381
382The instrument to do that is called a "condition variable", so called
383because they represent a condition that must become true.
384
302Condition variables can be created by calling the C<< AnyEvent->condvar >> 385Condition variables can be created by calling the C<< AnyEvent->condvar
303method without any arguments. 386>> method, usually without arguments. The only argument pair allowed is
387C<cb>, which specifies a callback to be called when the condition variable
388becomes true.
304 389
305A condition variable waits for a condition - precisely that the C<< 390After creation, the condition variable is "false" until it becomes "true"
306->broadcast >> method has been called. 391by calling the C<send> method (or calling the condition variable as if it
392were a callback, read about the caveats in the description for the C<<
393->send >> method).
307 394
308They are very useful to signal that a condition has been fulfilled, for 395Condition variables are similar to callbacks, except that you can
396optionally wait for them. They can also be called merge points - points
397in time where multiple outstanding events have been processed. And yet
398another way to call them is transactions - each condition variable can be
399used to represent a transaction, which finishes at some point and delivers
400a result.
401
402Condition variables are very useful to signal that something has finished,
309example, if you write a module that does asynchronous http requests, 403for example, if you write a module that does asynchronous http requests,
310then a condition variable would be the ideal candidate to signal the 404then a condition variable would be the ideal candidate to signal the
311availability of results. 405availability of results. The user can either act when the callback is
406called or can synchronously C<< ->recv >> for the results.
312 407
313You can also use condition variables to block your main program until 408You can also use them to simulate traditional event loops - for example,
314an event occurs - for example, you could C<< ->wait >> in your main 409you can block your main program until an event occurs - for example, you
315program until the user clicks the Quit button in your app, which would C<< 410could C<< ->recv >> in your main program until the user clicks the Quit
316->broadcast >> the "quit" event. 411button of your app, which would C<< ->send >> the "quit" event.
317 412
318Note that condition variables recurse into the event loop - if you have 413Note that condition variables recurse into the event loop - if you have
319two pirces of code that call C<< ->wait >> in a round-robbin fashion, you 414two pieces of code that call C<< ->recv >> in a round-robin fashion, you
320lose. Therefore, condition variables are good to export to your caller, but 415lose. Therefore, condition variables are good to export to your caller, but
321you should avoid making a blocking wait yourself, at least in callbacks, 416you should avoid making a blocking wait yourself, at least in callbacks,
322as this asks for trouble. 417as this asks for trouble.
323 418
324This object has two methods: 419Condition variables are represented by hash refs in perl, and the keys
420used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
421easy (it is often useful to build your own transaction class on top of
422AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
423it's C<new> method in your own C<new> method.
424
425There are two "sides" to a condition variable - the "producer side" which
426eventually calls C<< -> send >>, and the "consumer side", which waits
427for the send to occur.
428
429Example: wait for a timer.
430
431 # wait till the result is ready
432 my $result_ready = AnyEvent->condvar;
433
434 # do something such as adding a timer
435 # or socket watcher the calls $result_ready->send
436 # when the "result" is ready.
437 # in this case, we simply use a timer:
438 my $w = AnyEvent->timer (
439 after => 1,
440 cb => sub { $result_ready->send },
441 );
442
443 # this "blocks" (while handling events) till the callback
444 # calls send
445 $result_ready->recv;
446
447Example: wait for a timer, but take advantage of the fact that
448condition variables are also code references.
449
450 my $done = AnyEvent->condvar;
451 my $delay = AnyEvent->timer (after => 5, cb => $done);
452 $done->recv;
453
454=head3 METHODS FOR PRODUCERS
455
456These methods should only be used by the producing side, i.e. the
457code/module that eventually sends the signal. Note that it is also
458the producer side which creates the condvar in most cases, but it isn't
459uncommon for the consumer to create it as well.
325 460
326=over 4 461=over 4
327 462
463=item $cv->send (...)
464
465Flag the condition as ready - a running C<< ->recv >> and all further
466calls to C<recv> will (eventually) return after this method has been
467called. If nobody is waiting the send will be remembered.
468
469If a callback has been set on the condition variable, it is called
470immediately from within send.
471
472Any arguments passed to the C<send> call will be returned by all
473future C<< ->recv >> calls.
474
475Condition variables are overloaded so one can call them directly
476(as a code reference). Calling them directly is the same as calling
477C<send>. Note, however, that many C-based event loops do not handle
478overloading, so as tempting as it may be, passing a condition variable
479instead of a callback does not work. Both the pure perl and EV loops
480support overloading, however, as well as all functions that use perl to
481invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
482example).
483
484=item $cv->croak ($error)
485
486Similar to send, but causes all call's to C<< ->recv >> to invoke
487C<Carp::croak> with the given error message/object/scalar.
488
489This can be used to signal any errors to the condition variable
490user/consumer.
491
492=item $cv->begin ([group callback])
493
328=item $cv->wait 494=item $cv->end
329 495
330Wait (blocking if necessary) until the C<< ->broadcast >> method has been 496These two methods are EXPERIMENTAL and MIGHT CHANGE.
497
498These two methods can be used to combine many transactions/events into
499one. For example, a function that pings many hosts in parallel might want
500to use a condition variable for the whole process.
501
502Every call to C<< ->begin >> will increment a counter, and every call to
503C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
504>>, the (last) callback passed to C<begin> will be executed. That callback
505is I<supposed> to call C<< ->send >>, but that is not required. If no
506callback was set, C<send> will be called without any arguments.
507
508Let's clarify this with the ping example:
509
510 my $cv = AnyEvent->condvar;
511
512 my %result;
513 $cv->begin (sub { $cv->send (\%result) });
514
515 for my $host (@list_of_hosts) {
516 $cv->begin;
517 ping_host_then_call_callback $host, sub {
518 $result{$host} = ...;
519 $cv->end;
520 };
521 }
522
523 $cv->end;
524
525This code fragment supposedly pings a number of hosts and calls
526C<send> after results for all then have have been gathered - in any
527order. To achieve this, the code issues a call to C<begin> when it starts
528each ping request and calls C<end> when it has received some result for
529it. Since C<begin> and C<end> only maintain a counter, the order in which
530results arrive is not relevant.
531
532There is an additional bracketing call to C<begin> and C<end> outside the
533loop, which serves two important purposes: first, it sets the callback
534to be called once the counter reaches C<0>, and second, it ensures that
535C<send> is called even when C<no> hosts are being pinged (the loop
536doesn't execute once).
537
538This is the general pattern when you "fan out" into multiple subrequests:
539use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
540is called at least once, and then, for each subrequest you start, call
541C<begin> and for each subrequest you finish, call C<end>.
542
543=back
544
545=head3 METHODS FOR CONSUMERS
546
547These methods should only be used by the consuming side, i.e. the
548code awaits the condition.
549
550=over 4
551
552=item $cv->recv
553
554Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
331called on c<$cv>, while servicing other watchers normally. 555>> methods have been called on c<$cv>, while servicing other watchers
556normally.
332 557
333You can only wait once on a condition - additional calls will return 558You can only wait once on a condition - additional calls are valid but
334immediately. 559will return immediately.
560
561If an error condition has been set by calling C<< ->croak >>, then this
562function will call C<croak>.
563
564In list context, all parameters passed to C<send> will be returned,
565in scalar context only the first one will be returned.
335 566
336Not all event models support a blocking wait - some die in that case 567Not all event models support a blocking wait - some die in that case
337(programs might want to do that to stay interactive), so I<if you are 568(programs might want to do that to stay interactive), so I<if you are
338using this from a module, never require a blocking wait>, but let the 569using this from a module, never require a blocking wait>, but let the
339caller decide whether the call will block or not (for example, by coupling 570caller decide whether the call will block or not (for example, by coupling
340condition variables with some kind of request results and supporting 571condition variables with some kind of request results and supporting
341callbacks so the caller knows that getting the result will not block, 572callbacks so the caller knows that getting the result will not block,
342while still suppporting blocking waits if the caller so desires). 573while still supporting blocking waits if the caller so desires).
343 574
344Another reason I<never> to C<< ->wait >> in a module is that you cannot 575Another reason I<never> to C<< ->recv >> in a module is that you cannot
345sensibly have two C<< ->wait >>'s in parallel, as that would require 576sensibly have two C<< ->recv >>'s in parallel, as that would require
346multiple interpreters or coroutines/threads, none of which C<AnyEvent> 577multiple interpreters or coroutines/threads, none of which C<AnyEvent>
347can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and 578can supply.
348L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s
349from different coroutines, however).
350 579
351=item $cv->broadcast 580The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
581fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
582versions and also integrates coroutines into AnyEvent, making blocking
583C<< ->recv >> calls perfectly safe as long as they are done from another
584coroutine (one that doesn't run the event loop).
352 585
353Flag the condition as ready - a running C<< ->wait >> and all further 586You can ensure that C<< -recv >> never blocks by setting a callback and
354calls to C<wait> will (eventually) return after this method has been 587only calling C<< ->recv >> from within that callback (or at a later
355called. If nobody is waiting the broadcast will be remembered.. 588time). This will work even when the event loop does not support blocking
589waits otherwise.
590
591=item $bool = $cv->ready
592
593Returns true when the condition is "true", i.e. whether C<send> or
594C<croak> have been called.
595
596=item $cb = $cv->cb ([new callback])
597
598This is a mutator function that returns the callback set and optionally
599replaces it before doing so.
600
601The callback will be called when the condition becomes "true", i.e. when
602C<send> or C<croak> are called, with the only argument being the condition
603variable itself. Calling C<recv> inside the callback or at any later time
604is guaranteed not to block.
356 605
357=back 606=back
358
359Example:
360
361 # wait till the result is ready
362 my $result_ready = AnyEvent->condvar;
363
364 # do something such as adding a timer
365 # or socket watcher the calls $result_ready->broadcast
366 # when the "result" is ready.
367 # in this case, we simply use a timer:
368 my $w = AnyEvent->timer (
369 after => 1,
370 cb => sub { $result_ready->broadcast },
371 );
372
373 # this "blocks" (while handling events) till the watcher
374 # calls broadcast
375 $result_ready->wait;
376 607
377=head1 GLOBAL VARIABLES AND FUNCTIONS 608=head1 GLOBAL VARIABLES AND FUNCTIONS
378 609
379=over 4 610=over 4
380 611
386C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 617C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
387AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 618AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
388 619
389The known classes so far are: 620The known classes so far are:
390 621
391 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
392 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
393 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 622 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
394 AnyEvent::Impl::Event based on Event, second best choice. 623 AnyEvent::Impl::Event based on Event, second best choice.
624 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
395 AnyEvent::Impl::Glib based on Glib, third-best choice. 625 AnyEvent::Impl::Glib based on Glib, third-best choice.
396 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
397 AnyEvent::Impl::Tk based on Tk, very bad choice. 626 AnyEvent::Impl::Tk based on Tk, very bad choice.
398 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 627 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
399 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 628 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
400 AnyEvent::Impl::POE based on POE, not generic enough for full support. 629 AnyEvent::Impl::POE based on POE, not generic enough for full support.
401 630
414Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 643Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
415if necessary. You should only call this function right before you would 644if necessary. You should only call this function right before you would
416have created an AnyEvent watcher anyway, that is, as late as possible at 645have created an AnyEvent watcher anyway, that is, as late as possible at
417runtime. 646runtime.
418 647
648=item $guard = AnyEvent::post_detect { BLOCK }
649
650Arranges for the code block to be executed as soon as the event model is
651autodetected (or immediately if this has already happened).
652
653If called in scalar or list context, then it creates and returns an object
654that automatically removes the callback again when it is destroyed. See
655L<Coro::BDB> for a case where this is useful.
656
657=item @AnyEvent::post_detect
658
659If there are any code references in this array (you can C<push> to it
660before or after loading AnyEvent), then they will called directly after
661the event loop has been chosen.
662
663You should check C<$AnyEvent::MODEL> before adding to this array, though:
664if it contains a true value then the event loop has already been detected,
665and the array will be ignored.
666
667Best use C<AnyEvent::post_detect { BLOCK }> instead.
668
419=back 669=back
420 670
421=head1 WHAT TO DO IN A MODULE 671=head1 WHAT TO DO IN A MODULE
422 672
423As a module author, you should C<use AnyEvent> and call AnyEvent methods 673As a module author, you should C<use AnyEvent> and call AnyEvent methods
426Be careful when you create watchers in the module body - AnyEvent will 676Be careful when you create watchers in the module body - AnyEvent will
427decide which event module to use as soon as the first method is called, so 677decide which event module to use as soon as the first method is called, so
428by calling AnyEvent in your module body you force the user of your module 678by calling AnyEvent in your module body you force the user of your module
429to load the event module first. 679to load the event module first.
430 680
431Never call C<< ->wait >> on a condition variable unless you I<know> that 681Never call C<< ->recv >> on a condition variable unless you I<know> that
432the C<< ->broadcast >> method has been called on it already. This is 682the C<< ->send >> method has been called on it already. This is
433because it will stall the whole program, and the whole point of using 683because it will stall the whole program, and the whole point of using
434events is to stay interactive. 684events is to stay interactive.
435 685
436It is fine, however, to call C<< ->wait >> when the user of your module 686It is fine, however, to call C<< ->recv >> when the user of your module
437requests it (i.e. if you create a http request object ad have a method 687requests it (i.e. if you create a http request object ad have a method
438called C<results> that returns the results, it should call C<< ->wait >> 688called C<results> that returns the results, it should call C<< ->recv >>
439freely, as the user of your module knows what she is doing. always). 689freely, as the user of your module knows what she is doing. always).
440 690
441=head1 WHAT TO DO IN THE MAIN PROGRAM 691=head1 WHAT TO DO IN THE MAIN PROGRAM
442 692
443There will always be a single main program - the only place that should 693There will always be a single main program - the only place that should
445 695
446If it doesn't care, it can just "use AnyEvent" and use it itself, or not 696If it doesn't care, it can just "use AnyEvent" and use it itself, or not
447do anything special (it does not need to be event-based) and let AnyEvent 697do anything special (it does not need to be event-based) and let AnyEvent
448decide which implementation to chose if some module relies on it. 698decide which implementation to chose if some module relies on it.
449 699
450If the main program relies on a specific event model. For example, in 700If the main program relies on a specific event model - for example, in
451Gtk2 programs you have to rely on the Glib module. You should load the 701Gtk2 programs you have to rely on the Glib module - you should load the
452event module before loading AnyEvent or any module that uses it: generally 702event module before loading AnyEvent or any module that uses it: generally
453speaking, you should load it as early as possible. The reason is that 703speaking, you should load it as early as possible. The reason is that
454modules might create watchers when they are loaded, and AnyEvent will 704modules might create watchers when they are loaded, and AnyEvent will
455decide on the event model to use as soon as it creates watchers, and it 705decide on the event model to use as soon as it creates watchers, and it
456might chose the wrong one unless you load the correct one yourself. 706might chose the wrong one unless you load the correct one yourself.
457 707
458You can chose to use a rather inefficient pure-perl implementation by 708You can chose to use a pure-perl implementation by loading the
459loading the C<AnyEvent::Impl::Perl> module, which gives you similar 709C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
460behaviour everywhere, but letting AnyEvent chose is generally better. 710everywhere, but letting AnyEvent chose the model is generally better.
711
712=head2 MAINLOOP EMULATION
713
714Sometimes (often for short test scripts, or even standalone programs who
715only want to use AnyEvent), you do not want to run a specific event loop.
716
717In that case, you can use a condition variable like this:
718
719 AnyEvent->condvar->recv;
720
721This has the effect of entering the event loop and looping forever.
722
723Note that usually your program has some exit condition, in which case
724it is better to use the "traditional" approach of storing a condition
725variable somewhere, waiting for it, and sending it when the program should
726exit cleanly.
727
461 728
462=head1 OTHER MODULES 729=head1 OTHER MODULES
463 730
464The following is a non-exhaustive list of additional modules that use 731The following is a non-exhaustive list of additional modules that use
465AnyEvent and can therefore be mixed easily with other AnyEvent modules 732AnyEvent and can therefore be mixed easily with other AnyEvent modules
477 744
478Provide read and write buffers and manages watchers for reads and writes. 745Provide read and write buffers and manages watchers for reads and writes.
479 746
480=item L<AnyEvent::Socket> 747=item L<AnyEvent::Socket>
481 748
482Provides a means to do non-blocking connects, accepts etc. 749Provides various utility functions for (internet protocol) sockets,
750addresses and name resolution. Also functions to create non-blocking tcp
751connections or tcp servers, with IPv6 and SRV record support and more.
752
753=item L<AnyEvent::DNS>
754
755Provides rich asynchronous DNS resolver capabilities.
756
757=item L<AnyEvent::HTTP>
758
759A simple-to-use HTTP library that is capable of making a lot of concurrent
760HTTP requests.
483 761
484=item L<AnyEvent::HTTPD> 762=item L<AnyEvent::HTTPD>
485 763
486Provides a simple web application server framework. 764Provides a simple web application server framework.
487 765
488=item L<AnyEvent::DNS>
489
490Provides asynchronous DNS resolver capabilities, beyond what
491L<AnyEvent::Util> offers.
492
493=item L<AnyEvent::FastPing> 766=item L<AnyEvent::FastPing>
494 767
495The fastest ping in the west. 768The fastest ping in the west.
769
770=item L<AnyEvent::DBI>
771
772Executes DBI requests asynchronously in a proxy process.
496 773
497=item L<Net::IRC3> 774=item L<Net::IRC3>
498 775
499AnyEvent based IRC client module family. 776AnyEvent based IRC client module family.
500 777
511 788
512High level API for event-based execution flow control. 789High level API for event-based execution flow control.
513 790
514=item L<Coro> 791=item L<Coro>
515 792
516Has special support for AnyEvent. 793Has special support for AnyEvent via L<Coro::AnyEvent>.
794
795=item L<AnyEvent::AIO>, L<IO::AIO>
796
797Truly asynchronous I/O, should be in the toolbox of every event
798programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
799together.
800
801=item L<AnyEvent::BDB>, L<BDB>
802
803Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
804IO::AIO and AnyEvent together.
517 805
518=item L<IO::Lambda> 806=item L<IO::Lambda>
519 807
520The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 808The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
521
522=item L<IO::AIO>
523
524Truly asynchronous I/O, should be in the toolbox of every event
525programmer. Can be trivially made to use AnyEvent.
526
527=item L<BDB>
528
529Truly asynchronous Berkeley DB access. Can be trivially made to use
530AnyEvent.
531 809
532=back 810=back
533 811
534=cut 812=cut
535 813
538no warnings; 816no warnings;
539use strict; 817use strict;
540 818
541use Carp; 819use Carp;
542 820
543our $VERSION = '3.3'; 821our $VERSION = 4.152;
544our $MODEL; 822our $MODEL;
545 823
546our $AUTOLOAD; 824our $AUTOLOAD;
547our @ISA; 825our @ISA;
548 826
827our @REGISTRY;
828
829our $WIN32;
830
831BEGIN {
832 my $win32 = ! ! ($^O =~ /mswin32/i);
833 eval "sub WIN32(){ $win32 }";
834}
835
549our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 836our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
550 837
551our @REGISTRY; 838our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
839
840{
841 my $idx;
842 $PROTOCOL{$_} = ++$idx
843 for reverse split /\s*,\s*/,
844 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
845}
552 846
553my @models = ( 847my @models = (
554 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
555 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
556 [EV:: => AnyEvent::Impl::EV::], 848 [EV:: => AnyEvent::Impl::EV::],
557 [Event:: => AnyEvent::Impl::Event::], 849 [Event:: => AnyEvent::Impl::Event::],
558 [Glib:: => AnyEvent::Impl::Glib::],
559 [Tk:: => AnyEvent::Impl::Tk::],
560 [Wx:: => AnyEvent::Impl::POE::],
561 [Prima:: => AnyEvent::Impl::POE::],
562 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 850 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
563 # everything below here will not be autoprobed as the pureperl backend should work everywhere 851 # everything below here will not be autoprobed
852 # as the pureperl backend should work everywhere
853 # and is usually faster
854 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
855 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
564 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 856 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
565 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 857 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
566 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 858 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
859 [Wx:: => AnyEvent::Impl::POE::],
860 [Prima:: => AnyEvent::Impl::POE::],
567); 861);
568 862
569our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY); 863our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY);
864
865our @post_detect;
866
867sub post_detect(&) {
868 my ($cb) = @_;
869
870 if ($MODEL) {
871 $cb->();
872
873 1
874 } else {
875 push @post_detect, $cb;
876
877 defined wantarray
878 ? bless \$cb, "AnyEvent::Util::PostDetect"
879 : ()
880 }
881}
882
883sub AnyEvent::Util::PostDetect::DESTROY {
884 @post_detect = grep $_ != ${$_[0]}, @post_detect;
885}
570 886
571sub detect() { 887sub detect() {
572 unless ($MODEL) { 888 unless ($MODEL) {
573 no strict 'refs'; 889 no strict 'refs';
890 local $SIG{__DIE__};
574 891
575 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 892 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
576 my $model = "AnyEvent::Impl::$1"; 893 my $model = "AnyEvent::Impl::$1";
577 if (eval "require $model") { 894 if (eval "require $model") {
578 $MODEL = $model; 895 $MODEL = $model;
608 last; 925 last;
609 } 926 }
610 } 927 }
611 928
612 $MODEL 929 $MODEL
613 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event) or Glib."; 930 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
614 } 931 }
615 } 932 }
616 933
617 unshift @ISA, $MODEL; 934 unshift @ISA, $MODEL;
618 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 935 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
936
937 (shift @post_detect)->() while @post_detect;
619 } 938 }
620 939
621 $MODEL 940 $MODEL
622} 941}
623 942
633 $class->$func (@_); 952 $class->$func (@_);
634} 953}
635 954
636package AnyEvent::Base; 955package AnyEvent::Base;
637 956
957# default implementation for now and time
958
959use Time::HiRes ();
960
961sub time { Time::HiRes::time }
962sub now { Time::HiRes::time }
963
638# default implementation for ->condvar, ->wait, ->broadcast 964# default implementation for ->condvar
639 965
640sub condvar { 966sub condvar {
641 bless \my $flag, "AnyEvent::Base::CondVar" 967 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
642}
643
644sub AnyEvent::Base::CondVar::broadcast {
645 ${$_[0]}++;
646}
647
648sub AnyEvent::Base::CondVar::wait {
649 AnyEvent->one_event while !${$_[0]};
650} 968}
651 969
652# default implementation for ->signal 970# default implementation for ->signal
653 971
654our %SIG_CB; 972our %SIG_CB;
707 or Carp::croak "required option 'pid' is missing"; 1025 or Carp::croak "required option 'pid' is missing";
708 1026
709 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1027 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
710 1028
711 unless ($WNOHANG) { 1029 unless ($WNOHANG) {
712 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 1030 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
713 } 1031 }
714 1032
715 unless ($CHLD_W) { 1033 unless ($CHLD_W) {
716 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1034 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
717 # child could be a zombie already, so make at least one round 1035 # child could be a zombie already, so make at least one round
727 delete $PID_CB{$pid}{$cb}; 1045 delete $PID_CB{$pid}{$cb};
728 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1046 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
729 1047
730 undef $CHLD_W unless keys %PID_CB; 1048 undef $CHLD_W unless keys %PID_CB;
731} 1049}
1050
1051package AnyEvent::CondVar;
1052
1053our @ISA = AnyEvent::CondVar::Base::;
1054
1055package AnyEvent::CondVar::Base;
1056
1057use overload
1058 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1059 fallback => 1;
1060
1061sub _send {
1062 # nop
1063}
1064
1065sub send {
1066 my $cv = shift;
1067 $cv->{_ae_sent} = [@_];
1068 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1069 $cv->_send;
1070}
1071
1072sub croak {
1073 $_[0]{_ae_croak} = $_[1];
1074 $_[0]->send;
1075}
1076
1077sub ready {
1078 $_[0]{_ae_sent}
1079}
1080
1081sub _wait {
1082 AnyEvent->one_event while !$_[0]{_ae_sent};
1083}
1084
1085sub recv {
1086 $_[0]->_wait;
1087
1088 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
1089 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
1090}
1091
1092sub cb {
1093 $_[0]{_ae_cb} = $_[1] if @_ > 1;
1094 $_[0]{_ae_cb}
1095}
1096
1097sub begin {
1098 ++$_[0]{_ae_counter};
1099 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
1100}
1101
1102sub end {
1103 return if --$_[0]{_ae_counter};
1104 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1105}
1106
1107# undocumented/compatibility with pre-3.4
1108*broadcast = \&send;
1109*wait = \&_wait;
732 1110
733=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1111=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
734 1112
735This is an advanced topic that you do not normally need to use AnyEvent in 1113This is an advanced topic that you do not normally need to use AnyEvent in
736a module. This section is only of use to event loop authors who want to 1114a module. This section is only of use to event loop authors who want to
793model it chooses. 1171model it chooses.
794 1172
795=item C<PERL_ANYEVENT_MODEL> 1173=item C<PERL_ANYEVENT_MODEL>
796 1174
797This can be used to specify the event model to be used by AnyEvent, before 1175This can be used to specify the event model to be used by AnyEvent, before
798autodetection and -probing kicks in. It must be a string consisting 1176auto detection and -probing kicks in. It must be a string consisting
799entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1177entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
800and the resulting module name is loaded and if the load was successful, 1178and the resulting module name is loaded and if the load was successful,
801used as event model. If it fails to load AnyEvent will proceed with 1179used as event model. If it fails to load AnyEvent will proceed with
802autodetection and -probing. 1180auto detection and -probing.
803 1181
804This functionality might change in future versions. 1182This functionality might change in future versions.
805 1183
806For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1184For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
807could start your program like this: 1185could start your program like this:
808 1186
809 PERL_ANYEVENT_MODEL=Perl perl ... 1187 PERL_ANYEVENT_MODEL=Perl perl ...
1188
1189=item C<PERL_ANYEVENT_PROTOCOLS>
1190
1191Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1192for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1193of auto probing).
1194
1195Must be set to a comma-separated list of protocols or address families,
1196current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1197used, and preference will be given to protocols mentioned earlier in the
1198list.
1199
1200This variable can effectively be used for denial-of-service attacks
1201against local programs (e.g. when setuid), although the impact is likely
1202small, as the program has to handle connection errors already-
1203
1204Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1205but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1206- only support IPv4, never try to resolve or contact IPv6
1207addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1208IPv6, but prefer IPv6 over IPv4.
1209
1210=item C<PERL_ANYEVENT_EDNS0>
1211
1212Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1213for DNS. This extension is generally useful to reduce DNS traffic, but
1214some (broken) firewalls drop such DNS packets, which is why it is off by
1215default.
1216
1217Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1218EDNS0 in its DNS requests.
1219
1220=item C<PERL_ANYEVENT_MAX_FORKS>
1221
1222The maximum number of child processes that C<AnyEvent::Util::fork_call>
1223will create in parallel.
810 1224
811=back 1225=back
812 1226
813=head1 EXAMPLE PROGRAM 1227=head1 EXAMPLE PROGRAM
814 1228
825 poll => 'r', 1239 poll => 'r',
826 cb => sub { 1240 cb => sub {
827 warn "io event <$_[0]>\n"; # will always output <r> 1241 warn "io event <$_[0]>\n"; # will always output <r>
828 chomp (my $input = <STDIN>); # read a line 1242 chomp (my $input = <STDIN>); # read a line
829 warn "read: $input\n"; # output what has been read 1243 warn "read: $input\n"; # output what has been read
830 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1244 $cv->send if $input =~ /^q/i; # quit program if /^q/i
831 }, 1245 },
832 ); 1246 );
833 1247
834 my $time_watcher; # can only be used once 1248 my $time_watcher; # can only be used once
835 1249
840 }); 1254 });
841 } 1255 }
842 1256
843 new_timer; # create first timer 1257 new_timer; # create first timer
844 1258
845 $cv->wait; # wait until user enters /^q/i 1259 $cv->recv; # wait until user enters /^q/i
846 1260
847=head1 REAL-WORLD EXAMPLE 1261=head1 REAL-WORLD EXAMPLE
848 1262
849Consider the L<Net::FCP> module. It features (among others) the following 1263Consider the L<Net::FCP> module. It features (among others) the following
850API calls, which are to freenet what HTTP GET requests are to http: 1264API calls, which are to freenet what HTTP GET requests are to http:
900 syswrite $txn->{fh}, $txn->{request} 1314 syswrite $txn->{fh}, $txn->{request}
901 or die "connection or write error"; 1315 or die "connection or write error";
902 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1316 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
903 1317
904Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1318Again, C<fh_ready_r> waits till all data has arrived, and then stores the
905result and signals any possible waiters that the request ahs finished: 1319result and signals any possible waiters that the request has finished:
906 1320
907 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1321 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
908 1322
909 if (end-of-file or data complete) { 1323 if (end-of-file or data complete) {
910 $txn->{result} = $txn->{buf}; 1324 $txn->{result} = $txn->{buf};
911 $txn->{finished}->broadcast; 1325 $txn->{finished}->send;
912 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1326 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
913 } 1327 }
914 1328
915The C<result> method, finally, just waits for the finished signal (if the 1329The C<result> method, finally, just waits for the finished signal (if the
916request was already finished, it doesn't wait, of course, and returns the 1330request was already finished, it doesn't wait, of course, and returns the
917data: 1331data:
918 1332
919 $txn->{finished}->wait; 1333 $txn->{finished}->recv;
920 return $txn->{result}; 1334 return $txn->{result};
921 1335
922The actual code goes further and collects all errors (C<die>s, exceptions) 1336The actual code goes further and collects all errors (C<die>s, exceptions)
923that occured during request processing. The C<result> method detects 1337that occurred during request processing. The C<result> method detects
924whether an exception as thrown (it is stored inside the $txn object) 1338whether an exception as thrown (it is stored inside the $txn object)
925and just throws the exception, which means connection errors and other 1339and just throws the exception, which means connection errors and other
926problems get reported tot he code that tries to use the result, not in a 1340problems get reported tot he code that tries to use the result, not in a
927random callback. 1341random callback.
928 1342
959 1373
960 my $quit = AnyEvent->condvar; 1374 my $quit = AnyEvent->condvar;
961 1375
962 $fcp->txn_client_get ($url)->cb (sub { 1376 $fcp->txn_client_get ($url)->cb (sub {
963 ... 1377 ...
964 $quit->broadcast; 1378 $quit->send;
965 }); 1379 });
966 1380
967 $quit->wait; 1381 $quit->recv;
968 1382
969 1383
970=head1 BENCHMARKS 1384=head1 BENCHMARKS
971 1385
972To give you an idea of the performance and overheads that AnyEvent adds 1386To give you an idea of the performance and overheads that AnyEvent adds
974of various event loops I prepared some benchmarks. 1388of various event loops I prepared some benchmarks.
975 1389
976=head2 BENCHMARKING ANYEVENT OVERHEAD 1390=head2 BENCHMARKING ANYEVENT OVERHEAD
977 1391
978Here is a benchmark of various supported event models used natively and 1392Here is a benchmark of various supported event models used natively and
979through anyevent. The benchmark creates a lot of timers (with a zero 1393through AnyEvent. The benchmark creates a lot of timers (with a zero
980timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1394timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
981which it is), lets them fire exactly once and destroys them again. 1395which it is), lets them fire exactly once and destroys them again.
982 1396
983Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1397Source code for this benchmark is found as F<eg/bench> in the AnyEvent
984distribution. 1398distribution.
1001all watchers, to avoid adding memory overhead. That means closure creation 1415all watchers, to avoid adding memory overhead. That means closure creation
1002and memory usage is not included in the figures. 1416and memory usage is not included in the figures.
1003 1417
1004I<invoke> is the time, in microseconds, used to invoke a simple 1418I<invoke> is the time, in microseconds, used to invoke a simple
1005callback. The callback simply counts down a Perl variable and after it was 1419callback. The callback simply counts down a Perl variable and after it was
1006invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1420invoked "watcher" times, it would C<< ->send >> a condvar once to
1007signal the end of this phase. 1421signal the end of this phase.
1008 1422
1009I<destroy> is the time, in microseconds, that it takes to destroy a single 1423I<destroy> is the time, in microseconds, that it takes to destroy a single
1010watcher. 1424watcher.
1011 1425
1071file descriptor is dup()ed for each watcher. This shows that the dup() 1485file descriptor is dup()ed for each watcher. This shows that the dup()
1072employed by some adaptors is not a big performance issue (it does incur a 1486employed by some adaptors is not a big performance issue (it does incur a
1073hidden memory cost inside the kernel which is not reflected in the figures 1487hidden memory cost inside the kernel which is not reflected in the figures
1074above). 1488above).
1075 1489
1076C<POE>, regardless of underlying event loop (whether using its pure 1490C<POE>, regardless of underlying event loop (whether using its pure perl
1077perl select-based backend or the Event module, the POE-EV backend 1491select-based backend or the Event module, the POE-EV backend couldn't
1078couldn't be tested because it wasn't working) shows abysmal performance 1492be tested because it wasn't working) shows abysmal performance and
1079and memory usage: Watchers use almost 30 times as much memory as 1493memory usage with AnyEvent: Watchers use almost 30 times as much memory
1080EV watchers, and 10 times as much memory as Event (the high memory 1494as EV watchers, and 10 times as much memory as Event (the high memory
1081requirements are caused by requiring a session for each watcher). Watcher 1495requirements are caused by requiring a session for each watcher). Watcher
1082invocation speed is almost 900 times slower than with AnyEvent's pure perl 1496invocation speed is almost 900 times slower than with AnyEvent's pure perl
1497implementation.
1498
1083implementation. The design of the POE adaptor class in AnyEvent can not 1499The design of the POE adaptor class in AnyEvent can not really account
1084really account for this, as session creation overhead is small compared 1500for the performance issues, though, as session creation overhead is
1085to execution of the state machine, which is coded pretty optimally within 1501small compared to execution of the state machine, which is coded pretty
1086L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow. 1502optimally within L<AnyEvent::Impl::POE> (and while everybody agrees that
1503using multiple sessions is not a good approach, especially regarding
1504memory usage, even the author of POE could not come up with a faster
1505design).
1087 1506
1088=head3 Summary 1507=head3 Summary
1089 1508
1090=over 4 1509=over 4
1091 1510
1102 1521
1103=back 1522=back
1104 1523
1105=head2 BENCHMARKING THE LARGE SERVER CASE 1524=head2 BENCHMARKING THE LARGE SERVER CASE
1106 1525
1107This benchmark atcually benchmarks the event loop itself. It works by 1526This benchmark actually benchmarks the event loop itself. It works by
1108creating a number of "servers": each server consists of a socketpair, a 1527creating a number of "servers": each server consists of a socket pair, a
1109timeout watcher that gets reset on activity (but never fires), and an I/O 1528timeout watcher that gets reset on activity (but never fires), and an I/O
1110watcher waiting for input on one side of the socket. Each time the socket 1529watcher waiting for input on one side of the socket. Each time the socket
1111watcher reads a byte it will write that byte to a random other "server". 1530watcher reads a byte it will write that byte to a random other "server".
1112 1531
1113The effect is that there will be a lot of I/O watchers, only part of which 1532The effect is that there will be a lot of I/O watchers, only part of which
1114are active at any one point (so there is a constant number of active 1533are active at any one point (so there is a constant number of active
1115fds for each loop iterstaion, but which fds these are is random). The 1534fds for each loop iteration, but which fds these are is random). The
1116timeout is reset each time something is read because that reflects how 1535timeout is reset each time something is read because that reflects how
1117most timeouts work (and puts extra pressure on the event loops). 1536most timeouts work (and puts extra pressure on the event loops).
1118 1537
1119In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1538In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1120(1%) are active. This mirrors the activity of large servers with many 1539(1%) are active. This mirrors the activity of large servers with many
1121connections, most of which are idle at any one point in time. 1540connections, most of which are idle at any one point in time.
1122 1541
1123Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1542Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1124distribution. 1543distribution.
1126=head3 Explanation of the columns 1545=head3 Explanation of the columns
1127 1546
1128I<sockets> is the number of sockets, and twice the number of "servers" (as 1547I<sockets> is the number of sockets, and twice the number of "servers" (as
1129each server has a read and write socket end). 1548each server has a read and write socket end).
1130 1549
1131I<create> is the time it takes to create a socketpair (which is 1550I<create> is the time it takes to create a socket pair (which is
1132nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1551nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1133 1552
1134I<request>, the most important value, is the time it takes to handle a 1553I<request>, the most important value, is the time it takes to handle a
1135single "request", that is, reading the token from the pipe and forwarding 1554single "request", that is, reading the token from the pipe and forwarding
1136it to another server. This includes deleting the old timeout and creating 1555it to another server. This includes deleting the old timeout and creating
1170 1589
1171=head3 Summary 1590=head3 Summary
1172 1591
1173=over 4 1592=over 4
1174 1593
1175=item * The pure perl implementation performs extremely well, considering 1594=item * The pure perl implementation performs extremely well.
1176that it uses select.
1177 1595
1178=item * Avoid Glib or POE in large projects where performance matters. 1596=item * Avoid Glib or POE in large projects where performance matters.
1179 1597
1180=back 1598=back
1181 1599
1210speed most when you have lots of watchers, not when you only have a few of 1628speed most when you have lots of watchers, not when you only have a few of
1211them). 1629them).
1212 1630
1213EV is again fastest. 1631EV is again fastest.
1214 1632
1215Perl again comes second. It is noticably faster than the C-based event 1633Perl again comes second. It is noticeably faster than the C-based event
1216loops Event and Glib, although the difference is too small to really 1634loops Event and Glib, although the difference is too small to really
1217matter. 1635matter.
1218 1636
1219POE also performs much better in this case, but is is still far behind the 1637POE also performs much better in this case, but is is still far behind the
1220others. 1638others.
1230 1648
1231 1649
1232=head1 FORK 1650=head1 FORK
1233 1651
1234Most event libraries are not fork-safe. The ones who are usually are 1652Most event libraries are not fork-safe. The ones who are usually are
1235because they are so inefficient. Only L<EV> is fully fork-aware. 1653because they rely on inefficient but fork-safe C<select> or C<poll>
1654calls. Only L<EV> is fully fork-aware.
1236 1655
1237If you have to fork, you must either do so I<before> creating your first 1656If you have to fork, you must either do so I<before> creating your first
1238watcher OR you must not use AnyEvent at all in the child. 1657watcher OR you must not use AnyEvent at all in the child.
1239 1658
1240 1659
1248specified in the variable. 1667specified in the variable.
1249 1668
1250You can make AnyEvent completely ignore this variable by deleting it 1669You can make AnyEvent completely ignore this variable by deleting it
1251before the first watcher gets created, e.g. with a C<BEGIN> block: 1670before the first watcher gets created, e.g. with a C<BEGIN> block:
1252 1671
1253 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1672 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1254 1673
1255 use AnyEvent; 1674 use AnyEvent;
1675
1676Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1677be used to probe what backend is used and gain other information (which is
1678probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1679
1680
1681=head1 BUGS
1682
1683Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
1684to work around. If you suffer from memleaks, first upgrade to Perl 5.10
1685and check wether the leaks still show up. (Perl 5.10.0 has other annoying
1686mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
1687pronounced).
1256 1688
1257 1689
1258=head1 SEE ALSO 1690=head1 SEE ALSO
1259 1691
1260Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1692Utility functions: L<AnyEvent::Util>.
1261L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, 1693
1694Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1262L<Event::Lib>, L<Qt>, L<POE>. 1695L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1263 1696
1264Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1697Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1265L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1698L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1266L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1699L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1267L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1700L<AnyEvent::Impl::POE>.
1268 1701
1702Non-blocking file handles, sockets, TCP clients and
1703servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1704
1705Asynchronous DNS: L<AnyEvent::DNS>.
1706
1707Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1708
1269Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1709Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1270 1710
1271 1711
1272=head1 AUTHOR 1712=head1 AUTHOR
1273 1713
1274 Marc Lehmann <schmorp@schmorp.de> 1714 Marc Lehmann <schmorp@schmorp.de>
1275 http://home.schmorp.de/ 1715 http://home.schmorp.de/
1276 1716
1277=cut 1717=cut
1278 1718
12791 17191
1280 1720

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines