… | |
… | |
46 | that isn't itself. What's worse, all the potential users of your module |
46 | that isn't itself. What's worse, all the potential users of your module |
47 | are *also* forced to use the same event loop you use. |
47 | are *also* forced to use the same event loop you use. |
48 | |
48 | |
49 | AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works |
49 | AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works |
50 | fine. AnyEvent + Tk works fine etc. etc. but none of these work together |
50 | fine. AnyEvent + Tk works fine etc. etc. but none of these work together |
51 | with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your |
51 | with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your |
52 | module uses one of those, every user of your module has to use it, too. |
52 | module uses one of those, every user of your module has to use it, too. |
53 | But if your module uses AnyEvent, it works transparently with all event |
53 | But if your module uses AnyEvent, it works transparently with all event |
54 | models it supports (including stuff like POE and IO::Async, as long as |
54 | models it supports (including stuff like POE and IO::Async, as long as |
55 | those use one of the supported event loops. It is trivial to add new |
55 | those use one of the supported event loops. It is trivial to add new |
56 | event loops to AnyEvent, too, so it is future-proof). |
56 | event loops to AnyEvent, too, so it is future-proof). |
… | |
… | |
60 | modules, you get an enormous amount of code and strict rules you have to |
60 | modules, you get an enormous amount of code and strict rules you have to |
61 | follow. AnyEvent, on the other hand, is lean and up to the point, by |
61 | follow. AnyEvent, on the other hand, is lean and up to the point, by |
62 | only offering the functionality that is necessary, in as thin as a |
62 | only offering the functionality that is necessary, in as thin as a |
63 | wrapper as technically possible. |
63 | wrapper as technically possible. |
64 | |
64 | |
|
|
65 | Of course, AnyEvent comes with a big (and fully optional!) toolbox of |
|
|
66 | useful functionality, such as an asynchronous DNS resolver, 100% |
|
|
67 | non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms |
|
|
68 | such as Windows) and lots of real-world knowledge and workarounds for |
|
|
69 | platform bugs and differences. |
|
|
70 | |
65 | Of course, if you want lots of policy (this can arguably be somewhat |
71 | Now, if you *do want* lots of policy (this can arguably be somewhat |
66 | useful) and you want to force your users to use the one and only event |
72 | useful) and you want to force your users to use the one and only event |
67 | model, you should *not* use this module. |
73 | model, you should *not* use this module. |
68 | |
74 | |
69 | DESCRIPTION |
75 | DESCRIPTION |
70 | AnyEvent provides an identical interface to multiple event loops. This |
76 | AnyEvent provides an identical interface to multiple event loops. This |
… | |
… | |
99 | starts using it, all bets are off. Maybe you should tell their authors |
105 | starts using it, all bets are off. Maybe you should tell their authors |
100 | to use AnyEvent so their modules work together with others seamlessly... |
106 | to use AnyEvent so their modules work together with others seamlessly... |
101 | |
107 | |
102 | The pure-perl implementation of AnyEvent is called |
108 | The pure-perl implementation of AnyEvent is called |
103 | "AnyEvent::Impl::Perl". Like other event modules you can load it |
109 | "AnyEvent::Impl::Perl". Like other event modules you can load it |
104 | explicitly. |
110 | explicitly and enjoy the high availability of that event loop :) |
105 | |
111 | |
106 | WATCHERS |
112 | WATCHERS |
107 | AnyEvent has the central concept of a *watcher*, which is an object that |
113 | AnyEvent has the central concept of a *watcher*, which is an object that |
108 | stores relevant data for each kind of event you are waiting for, such as |
114 | stores relevant data for each kind of event you are waiting for, such as |
109 | the callback to call, the file handle to watch, etc. |
115 | the callback to call, the file handle to watch, etc. |
… | |
… | |
219 | (ev_timer, based on true relative time) and absolute (ev_periodic, based |
225 | (ev_timer, based on true relative time) and absolute (ev_periodic, based |
220 | on wallclock time) timers. |
226 | on wallclock time) timers. |
221 | |
227 | |
222 | AnyEvent always prefers relative timers, if available, matching the |
228 | AnyEvent always prefers relative timers, if available, matching the |
223 | AnyEvent API. |
229 | AnyEvent API. |
|
|
230 | |
|
|
231 | AnyEvent has two additional methods that return the "current time": |
|
|
232 | |
|
|
233 | AnyEvent->time |
|
|
234 | This returns the "current wallclock time" as a fractional number of |
|
|
235 | seconds since the Epoch (the same thing as "time" or |
|
|
236 | "Time::HiRes::time" return, and the result is guaranteed to be |
|
|
237 | compatible with those). |
|
|
238 | |
|
|
239 | It progresses independently of any event loop processing, i.e. each |
|
|
240 | call will check the system clock, which usually gets updated |
|
|
241 | frequently. |
|
|
242 | |
|
|
243 | AnyEvent->now |
|
|
244 | This also returns the "current wallclock time", but unlike "time", |
|
|
245 | above, this value might change only once per event loop iteration, |
|
|
246 | depending on the event loop (most return the same time as "time", |
|
|
247 | above). This is the time that AnyEvent's timers get scheduled |
|
|
248 | against. |
|
|
249 | |
|
|
250 | *In almost all cases (in all cases if you don't care), this is the |
|
|
251 | function to call when you want to know the current time.* |
|
|
252 | |
|
|
253 | This function is also often faster then "AnyEvent->time", and thus |
|
|
254 | the preferred method if you want some timestamp (for example, |
|
|
255 | AnyEvent::Handle uses this to update it's activity timeouts). |
|
|
256 | |
|
|
257 | The rest of this section is only of relevance if you try to be very |
|
|
258 | exact with your timing, you can skip it without bad conscience. |
|
|
259 | |
|
|
260 | For a practical example of when these times differ, consider |
|
|
261 | Event::Lib and EV and the following set-up: |
|
|
262 | |
|
|
263 | The event loop is running and has just invoked one of your callback |
|
|
264 | at time=500 (assume no other callbacks delay processing). In your |
|
|
265 | callback, you wait a second by executing "sleep 1" (blocking the |
|
|
266 | process for a second) and then (at time=501) you create a relative |
|
|
267 | timer that fires after three seconds. |
|
|
268 | |
|
|
269 | With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both |
|
|
270 | return 501, because that is the current time, and the timer will be |
|
|
271 | scheduled to fire at time=504 (501 + 3). |
|
|
272 | |
|
|
273 | With EV, "AnyEvent->time" returns 501 (as that is the current time), |
|
|
274 | but "AnyEvent->now" returns 500, as that is the time the last event |
|
|
275 | processing phase started. With EV, your timer gets scheduled to run |
|
|
276 | at time=503 (500 + 3). |
|
|
277 | |
|
|
278 | In one sense, Event::Lib is more exact, as it uses the current time |
|
|
279 | regardless of any delays introduced by event processing. However, |
|
|
280 | most callbacks do not expect large delays in processing, so this |
|
|
281 | causes a higher drift (and a lot more system calls to get the |
|
|
282 | current time). |
|
|
283 | |
|
|
284 | In another sense, EV is more exact, as your timer will be scheduled |
|
|
285 | at the same time, regardless of how long event processing actually |
|
|
286 | took. |
|
|
287 | |
|
|
288 | In either case, if you care (and in most cases, you don't), then you |
|
|
289 | can get whatever behaviour you want with any event loop, by taking |
|
|
290 | the difference between "AnyEvent->time" and "AnyEvent->now" into |
|
|
291 | account. |
224 | |
292 | |
225 | SIGNAL WATCHERS |
293 | SIGNAL WATCHERS |
226 | You can watch for signals using a signal watcher, "signal" is the signal |
294 | You can watch for signals using a signal watcher, "signal" is the signal |
227 | *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked |
295 | *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked |
228 | whenever a signal occurs. |
296 | whenever a signal occurs. |
… | |
… | |
303 | "cb", which specifies a callback to be called when the condition |
371 | "cb", which specifies a callback to be called when the condition |
304 | variable becomes true. |
372 | variable becomes true. |
305 | |
373 | |
306 | After creation, the condition variable is "false" until it becomes |
374 | After creation, the condition variable is "false" until it becomes |
307 | "true" by calling the "send" method (or calling the condition variable |
375 | "true" by calling the "send" method (or calling the condition variable |
308 | as if it were a callback). |
376 | as if it were a callback, read about the caveats in the description for |
|
|
377 | the "->send" method). |
309 | |
378 | |
310 | Condition variables are similar to callbacks, except that you can |
379 | Condition variables are similar to callbacks, except that you can |
311 | optionally wait for them. They can also be called merge points - points |
380 | optionally wait for them. They can also be called merge points - points |
312 | in time where multiple outstanding events have been processed. And yet |
381 | in time where multiple outstanding events have been processed. And yet |
313 | another way to call them is transactions - each condition variable can |
382 | another way to call them is transactions - each condition variable can |
… | |
… | |
383 | Any arguments passed to the "send" call will be returned by all |
452 | Any arguments passed to the "send" call will be returned by all |
384 | future "->recv" calls. |
453 | future "->recv" calls. |
385 | |
454 | |
386 | Condition variables are overloaded so one can call them directly (as |
455 | Condition variables are overloaded so one can call them directly (as |
387 | a code reference). Calling them directly is the same as calling |
456 | a code reference). Calling them directly is the same as calling |
388 | "send". |
457 | "send". Note, however, that many C-based event loops do not handle |
|
|
458 | overloading, so as tempting as it may be, passing a condition |
|
|
459 | variable instead of a callback does not work. Both the pure perl and |
|
|
460 | EV loops support overloading, however, as well as all functions that |
|
|
461 | use perl to invoke a callback (as in AnyEvent::Socket and |
|
|
462 | AnyEvent::DNS for example). |
389 | |
463 | |
390 | $cv->croak ($error) |
464 | $cv->croak ($error) |
391 | Similar to send, but causes all call's to "->recv" to invoke |
465 | Similar to send, but causes all call's to "->recv" to invoke |
392 | "Carp::croak" with the given error message/object/scalar. |
466 | "Carp::croak" with the given error message/object/scalar. |
393 | |
467 | |
… | |
… | |
578 | If it doesn't care, it can just "use AnyEvent" and use it itself, or not |
652 | If it doesn't care, it can just "use AnyEvent" and use it itself, or not |
579 | do anything special (it does not need to be event-based) and let |
653 | do anything special (it does not need to be event-based) and let |
580 | AnyEvent decide which implementation to chose if some module relies on |
654 | AnyEvent decide which implementation to chose if some module relies on |
581 | it. |
655 | it. |
582 | |
656 | |
583 | If the main program relies on a specific event model. For example, in |
657 | If the main program relies on a specific event model - for example, in |
584 | Gtk2 programs you have to rely on the Glib module. You should load the |
658 | Gtk2 programs you have to rely on the Glib module - you should load the |
585 | event module before loading AnyEvent or any module that uses it: |
659 | event module before loading AnyEvent or any module that uses it: |
586 | generally speaking, you should load it as early as possible. The reason |
660 | generally speaking, you should load it as early as possible. The reason |
587 | is that modules might create watchers when they are loaded, and AnyEvent |
661 | is that modules might create watchers when they are loaded, and AnyEvent |
588 | will decide on the event model to use as soon as it creates watchers, |
662 | will decide on the event model to use as soon as it creates watchers, |
589 | and it might chose the wrong one unless you load the correct one |
663 | and it might chose the wrong one unless you load the correct one |
590 | yourself. |
664 | yourself. |
591 | |
665 | |
592 | You can chose to use a rather inefficient pure-perl implementation by |
666 | You can chose to use a pure-perl implementation by loading the |
593 | loading the "AnyEvent::Impl::Perl" module, which gives you similar |
667 | "AnyEvent::Impl::Perl" module, which gives you similar behaviour |
594 | behaviour everywhere, but letting AnyEvent chose is generally better. |
668 | everywhere, but letting AnyEvent chose the model is generally better. |
|
|
669 | |
|
|
670 | MAINLOOP EMULATION |
|
|
671 | Sometimes (often for short test scripts, or even standalone programs who |
|
|
672 | only want to use AnyEvent), you do not want to run a specific event |
|
|
673 | loop. |
|
|
674 | |
|
|
675 | In that case, you can use a condition variable like this: |
|
|
676 | |
|
|
677 | AnyEvent->condvar->recv; |
|
|
678 | |
|
|
679 | This has the effect of entering the event loop and looping forever. |
|
|
680 | |
|
|
681 | Note that usually your program has some exit condition, in which case it |
|
|
682 | is better to use the "traditional" approach of storing a condition |
|
|
683 | variable somewhere, waiting for it, and sending it when the program |
|
|
684 | should exit cleanly. |
595 | |
685 | |
596 | OTHER MODULES |
686 | OTHER MODULES |
597 | The following is a non-exhaustive list of additional modules that use |
687 | The following is a non-exhaustive list of additional modules that use |
598 | AnyEvent and can therefore be mixed easily with other AnyEvent modules |
688 | AnyEvent and can therefore be mixed easily with other AnyEvent modules |
599 | in the same program. Some of the modules come with AnyEvent, some are |
689 | in the same program. Some of the modules come with AnyEvent, some are |
… | |
… | |
612 | Provides various utility functions for (internet protocol) sockets, |
702 | Provides various utility functions for (internet protocol) sockets, |
613 | addresses and name resolution. Also functions to create non-blocking |
703 | addresses and name resolution. Also functions to create non-blocking |
614 | tcp connections or tcp servers, with IPv6 and SRV record support and |
704 | tcp connections or tcp servers, with IPv6 and SRV record support and |
615 | more. |
705 | more. |
616 | |
706 | |
|
|
707 | AnyEvent::DNS |
|
|
708 | Provides rich asynchronous DNS resolver capabilities. |
|
|
709 | |
617 | AnyEvent::HTTPD |
710 | AnyEvent::HTTPD |
618 | Provides a simple web application server framework. |
711 | Provides a simple web application server framework. |
619 | |
|
|
620 | AnyEvent::DNS |
|
|
621 | Provides rich asynchronous DNS resolver capabilities. |
|
|
622 | |
712 | |
623 | AnyEvent::FastPing |
713 | AnyEvent::FastPing |
624 | The fastest ping in the west. |
714 | The fastest ping in the west. |
625 | |
715 | |
626 | Net::IRC3 |
716 | Net::IRC3 |
… | |
… | |
753 | but some (broken) firewalls drop such DNS packets, which is why it |
843 | but some (broken) firewalls drop such DNS packets, which is why it |
754 | is off by default. |
844 | is off by default. |
755 | |
845 | |
756 | Setting this variable to 1 will cause AnyEvent::DNS to announce |
846 | Setting this variable to 1 will cause AnyEvent::DNS to announce |
757 | EDNS0 in its DNS requests. |
847 | EDNS0 in its DNS requests. |
|
|
848 | |
|
|
849 | "PERL_ANYEVENT_MAX_FORKS" |
|
|
850 | The maximum number of child processes that |
|
|
851 | "AnyEvent::Util::fork_call" will create in parallel. |
758 | |
852 | |
759 | EXAMPLE PROGRAM |
853 | EXAMPLE PROGRAM |
760 | The following program uses an I/O watcher to read data from STDIN, a |
854 | The following program uses an I/O watcher to read data from STDIN, a |
761 | timer to display a message once per second, and a condition variable to |
855 | timer to display a message once per second, and a condition variable to |
762 | quit the program when the user enters quit: |
856 | quit the program when the user enters quit: |