… | |
… | |
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. |
… | |
… | |
775 | 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 |
776 | is off by default. |
844 | is off by default. |
777 | |
845 | |
778 | Setting this variable to 1 will cause AnyEvent::DNS to announce |
846 | Setting this variable to 1 will cause AnyEvent::DNS to announce |
779 | 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. |
780 | |
852 | |
781 | EXAMPLE PROGRAM |
853 | EXAMPLE PROGRAM |
782 | 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 |
783 | 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 |
784 | quit the program when the user enters quit: |
856 | quit the program when the user enters quit: |