1 | NAME |
1 | NAME |
2 | AnyEvent - provide framework for multiple event loops |
2 | AnyEvent - provide framework for multiple event loops |
3 | |
3 | |
4 | EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported |
4 | EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt - |
5 | event loops |
5 | various supported event loops |
6 | |
6 | |
7 | SYNOPSIS |
7 | SYNOPSIS |
8 | use AnyEvent; |
8 | use AnyEvent; |
9 | |
9 | |
10 | my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { |
10 | my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { |
… | |
… | |
76 | module. |
76 | module. |
77 | |
77 | |
78 | During the first call of any watcher-creation method, the module tries |
78 | During the first call of any watcher-creation method, the module tries |
79 | to detect the currently loaded event loop by probing whether one of the |
79 | to detect the currently loaded event loop by probing whether one of the |
80 | following modules is already loaded: Coro::EV, Coro::Event, EV, Event, |
80 | following modules is already loaded: Coro::EV, Coro::Event, EV, Event, |
81 | Glib, Tk. The first one found is used. If none are found, the module |
81 | Glib, Tk, Event::Lib, Qt. The first one found is used. If none are |
82 | tries to load these modules in the stated order. The first one that can |
82 | found, the module tries to load these modules (excluding Event::Lib and |
83 | be successfully loaded will be used. If, after this, still none could be |
83 | Qt) in the order given. The first one that can be successfully loaded |
84 | found, AnyEvent will fall back to a pure-perl event loop, which is not |
84 | will be used. If, after this, still none could be found, AnyEvent will |
85 | very efficient, but should work everywhere. |
85 | fall back to a pure-perl event loop, which is not very efficient, but |
|
|
86 | should work everywhere. |
86 | |
87 | |
87 | Because AnyEvent first checks for modules that are already loaded, |
88 | Because AnyEvent first checks for modules that are already loaded, |
88 | loading an event model explicitly before first using AnyEvent will |
89 | loading an event model explicitly before first using AnyEvent will |
89 | likely make that model the default. For example: |
90 | likely make that model the default. For example: |
90 | |
91 | |
… | |
… | |
138 | "fh" the Perl *file handle* (*not* file descriptor) to watch for events. |
139 | "fh" the Perl *file handle* (*not* file descriptor) to watch for events. |
139 | "poll" must be a string that is either "r" or "w", which creates a |
140 | "poll" must be a string that is either "r" or "w", which creates a |
140 | watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" |
141 | watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" |
141 | is the callback to invoke each time the file handle becomes ready. |
142 | is the callback to invoke each time the file handle becomes ready. |
142 | |
143 | |
143 | File handles will be kept alive, so as long as the watcher exists, the |
144 | As long as the I/O watcher exists it will keep the file descriptor or a |
144 | file handle exists, too. |
145 | copy of it alive/open. |
145 | |
146 | |
146 | It is not allowed to close a file handle as long as any watcher is |
147 | It is not allowed to close a file handle as long as any watcher is |
147 | active on the underlying file descriptor. |
148 | active on the underlying file descriptor. |
148 | |
149 | |
149 | Some event loops issue spurious readyness notifications, so you should |
150 | Some event loops issue spurious readyness notifications, so you should |
… | |
… | |
200 | o'clock"). |
201 | o'clock"). |
201 | |
202 | |
202 | While most event loops expect timers to specified in a relative way, |
203 | While most event loops expect timers to specified in a relative way, |
203 | they use absolute time internally. This makes a difference when your |
204 | they use absolute time internally. This makes a difference when your |
204 | clock "jumps", for example, when ntp decides to set your clock backwards |
205 | clock "jumps", for example, when ntp decides to set your clock backwards |
205 | from the wrong 2014-01-01 to 2008-01-01, a watcher that you created to |
206 | from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is |
206 | fire "after" a second might actually take six years to finally fire. |
207 | supposed to fire "after" a second might actually take six years to |
|
|
208 | finally fire. |
207 | |
209 | |
208 | AnyEvent cannot compensate for this. The only event loop that is |
210 | AnyEvent cannot compensate for this. The only event loop that is |
209 | conscious about these issues is EV, which offers both relative |
211 | conscious about these issues is EV, which offers both relative |
210 | (ev_timer) and absolute (ev_periodic) timers. |
212 | (ev_timer, based on true relative time) and absolute (ev_periodic, based |
|
|
213 | on wallclock time) timers. |
211 | |
214 | |
212 | AnyEvent always prefers relative timers, if available, matching the |
215 | AnyEvent always prefers relative timers, if available, matching the |
213 | AnyEvent API. |
216 | AnyEvent API. |
214 | |
217 | |
215 | SIGNAL WATCHERS |
218 | SIGNAL WATCHERS |
216 | You can watch for signals using a signal watcher, "signal" is the signal |
219 | You can watch for signals using a signal watcher, "signal" is the signal |
217 | *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked |
220 | *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked |
218 | whenever a signal occurs. |
221 | whenever a signal occurs. |
219 | |
222 | |
220 | Multiple signals occurances can be clumped together into one callback |
223 | Multiple signal occurances can be clumped together into one callback |
221 | invocation, and callback invocation will be synchronous. synchronous |
224 | invocation, and callback invocation will be synchronous. synchronous |
222 | means that it might take a while until the signal gets handled by the |
225 | means that it might take a while until the signal gets handled by the |
223 | process, but it is guarenteed not to interrupt any other callbacks. |
226 | process, but it is guarenteed not to interrupt any other callbacks. |
224 | |
227 | |
225 | The main advantage of using these watchers is that you can share a |
228 | The main advantage of using these watchers is that you can share a |
… | |
… | |
332 | |
335 | |
333 | The known classes so far are: |
336 | The known classes so far are: |
334 | |
337 | |
335 | AnyEvent::Impl::CoroEV based on Coro::EV, best choice. |
338 | AnyEvent::Impl::CoroEV based on Coro::EV, best choice. |
336 | AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. |
339 | AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. |
337 | AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). |
340 | AnyEvent::Impl::EV based on EV (an interface to libev, best choice). |
338 | AnyEvent::Impl::Event based on Event, also second best choice :) |
341 | AnyEvent::Impl::Event based on Event, second best choice. |
339 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
342 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
340 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
343 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
341 | AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. |
344 | AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. |
|
|
345 | AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). |
|
|
346 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
342 | |
347 | |
343 | AnyEvent::detect |
348 | AnyEvent::detect |
344 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
349 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
345 | if necessary. You should only call this function right before you |
350 | if necessary. You should only call this function right before you |
346 | would have created an AnyEvent watcher anyway, that is, as late as |
351 | would have created an AnyEvent watcher anyway, that is, as late as |
… | |
… | |
431 | must not be done in an interactive application, so it makes sense. |
436 | must not be done in an interactive application, so it makes sense. |
432 | |
437 | |
433 | ENVIRONMENT VARIABLES |
438 | ENVIRONMENT VARIABLES |
434 | The following environment variables are used by this module: |
439 | The following environment variables are used by this module: |
435 | |
440 | |
436 | "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, cause AnyEvent to |
441 | "PERL_ANYEVENT_VERBOSE" |
437 | report to STDERR which event model it chooses. |
442 | When set to 2 or higher, cause AnyEvent to report to STDERR which |
|
|
443 | event model it chooses. |
|
|
444 | |
|
|
445 | "PERL_ANYEVENT_MODEL" |
|
|
446 | This can be used to specify the event model to be used by AnyEvent, |
|
|
447 | before autodetection and -probing kicks in. It must be a string |
|
|
448 | consisting entirely of ASCII letters. The string "AnyEvent::Impl::" |
|
|
449 | gets prepended and the resulting module name is loaded and if the |
|
|
450 | load was successful, used as event model. If it fails to load |
|
|
451 | AnyEvent will proceed with autodetection and -probing. |
|
|
452 | |
|
|
453 | This functionality might change in future versions. |
|
|
454 | |
|
|
455 | For example, to force the pure perl model (AnyEvent::Impl::Perl) you |
|
|
456 | could start your program like this: |
|
|
457 | |
|
|
458 | PERL_ANYEVENT_MODEL=Perl perl ... |
438 | |
459 | |
439 | EXAMPLE PROGRAM |
460 | EXAMPLE PROGRAM |
440 | The following program uses an IO watcher to read data from STDIN, a |
461 | The following program uses an IO watcher to read data from STDIN, a |
441 | timer to display a message once per second, and a condition variable to |
462 | timer to display a message once per second, and a condition variable to |
442 | quit the program when the user enters quit: |
463 | quit the program when the user enters quit: |
… | |
… | |
588 | $quit->broadcast; |
609 | $quit->broadcast; |
589 | }); |
610 | }); |
590 | |
611 | |
591 | $quit->wait; |
612 | $quit->wait; |
592 | |
613 | |
|
|
614 | FORK |
|
|
615 | Most event libraries are not fork-safe. The ones who are usually are |
|
|
616 | because they are so inefficient. Only EV is fully fork-aware. |
|
|
617 | |
|
|
618 | If you have to fork, you must either do so *before* creating your first |
|
|
619 | watcher OR you must not use AnyEvent at all in the child. |
|
|
620 | |
|
|
621 | SECURITY CONSIDERATIONS |
|
|
622 | AnyEvent can be forced to load any event model via |
|
|
623 | $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used |
|
|
624 | to execute arbitrary code or directly gain access, it can easily be used |
|
|
625 | to make the program hang or malfunction in subtle ways, as AnyEvent |
|
|
626 | watchers will not be active when the program uses a different event |
|
|
627 | model than specified in the variable. |
|
|
628 | |
|
|
629 | You can make AnyEvent completely ignore this variable by deleting it |
|
|
630 | before the first watcher gets created, e.g. with a "BEGIN" block: |
|
|
631 | |
|
|
632 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
|
|
633 | |
|
|
634 | use AnyEvent; |
|
|
635 | |
593 | SEE ALSO |
636 | SEE ALSO |
594 | Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, |
637 | Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, |
595 | Glib::Event, Glib, Coro, Tk. |
638 | Glib::Event, Glib, Coro, Tk, Event::Lib, Qt. |
596 | |
639 | |
597 | Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, |
640 | Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, |
598 | AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, |
641 | AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, |
599 | AnyEvent::Impl::Tk, AnyEvent::Impl::Perl. |
642 | AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, |
|
|
643 | AnyEvent::Impl::Qt. |
600 | |
644 | |
601 | Nontrivial usage examples: Net::FCP, Net::XMPP2. |
645 | Nontrivial usage examples: Net::FCP, Net::XMPP2. |
602 | |
646 | |
|
|
647 | AUTHOR |
|
|
648 | Marc Lehmann <schmorp@schmorp.de> |
|
|
649 | http://home.schmorp.de/ |
603 | |
650 | |