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

Comparing AnyEvent/README (file contents):
Revision 1.23 by root, Mon May 26 06:04:38 2008 UTC vs.
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC

… …
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
69DESCRIPTION 75DESCRIPTION
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
106WATCHERS 112WATCHERS
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
781EXAMPLE PROGRAM 853EXAMPLE 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:

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines