1 | NAME |
1 | NAME |
2 | AnyEvent - provide framework for multiple event loops |
2 | AnyEvent - provide framework for multiple event loops |
3 | |
3 | |
4 | Event, Coro, Glib, Tk, Perl - various supported event loops |
4 | EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported |
|
|
5 | event loops |
5 | |
6 | |
6 | SYNOPSIS |
7 | SYNOPSIS |
7 | use AnyEvent; |
8 | use AnyEvent; |
8 | |
9 | |
9 | my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { |
10 | my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { |
… | |
… | |
69 | The interface itself is vaguely similar but not identical to the Event |
70 | The interface itself is vaguely similar but not identical to the Event |
70 | module. |
71 | module. |
71 | |
72 | |
72 | On the first call of any method, the module tries to detect the |
73 | On the first call of any method, the module tries to detect the |
73 | currently loaded event loop by probing wether any of the following |
74 | currently loaded event loop by probing wether any of the following |
74 | modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is |
75 | modules is loaded: Coro::EV, Coro::Event, EV, Event, Glib, Tk. The first |
75 | used. If none is found, the module tries to load these modules in the |
76 | one found is used. If none are found, the module tries to load these |
76 | order given. The first one that could be successfully loaded will be |
77 | modules in the order given. The first one that could be successfully |
77 | used. If still none could be found, AnyEvent will fall back to a |
78 | loaded will be used. If still none could be found, AnyEvent will fall |
78 | pure-perl event loop, which is also not very efficient. |
79 | back to a pure-perl event loop, which is also not very efficient. |
79 | |
80 | |
80 | Because AnyEvent first checks for modules that are already loaded, |
81 | Because AnyEvent first checks for modules that are already loaded, |
81 | loading an Event model explicitly before first using AnyEvent will |
82 | loading an Event model explicitly before first using AnyEvent will |
82 | likely make that model the default. For example: |
83 | likely make that model the default. For example: |
83 | |
84 | |
… | |
… | |
110 | "fh" the Perl *filehandle* (not filedescriptor) to watch for events. |
111 | "fh" the Perl *filehandle* (not filedescriptor) to watch for events. |
111 | "poll" must be a string that is either "r" or "w", that creates a |
112 | "poll" must be a string that is either "r" or "w", that creates a |
112 | watcher waiting for "r"eadable or "w"ritable events. "cb" the callback |
113 | watcher waiting for "r"eadable or "w"ritable events. "cb" the callback |
113 | to invoke everytime the filehandle becomes ready. |
114 | to invoke everytime the filehandle becomes ready. |
114 | |
115 | |
115 | Only one io watcher per "fh" and "poll" combination is allowed (i.e. on |
|
|
116 | a socket you can have one r + one w, not any more (limitation comes from |
|
|
117 | Tk - if you are sure you are not using Tk this limitation is gone). |
|
|
118 | |
|
|
119 | Filehandles will be kept alive, so as long as the watcher exists, the |
116 | Filehandles will be kept alive, so as long as the watcher exists, the |
120 | filehandle exists, too. |
117 | filehandle exists, too. |
121 | |
118 | |
122 | Example: |
119 | Example: |
123 | |
120 | |
… | |
… | |
166 | |
163 | |
167 | $cv->wait |
164 | $cv->wait |
168 | Wait (blocking if necessary) until the "->broadcast" method has been |
165 | Wait (blocking if necessary) until the "->broadcast" method has been |
169 | called on c<$cv>, while servicing other watchers normally. |
166 | called on c<$cv>, while servicing other watchers normally. |
170 | |
167 | |
171 | Not all event models support a blocking wait - some die in that |
|
|
172 | case, so if you are using this from a module, never require a |
|
|
173 | blocking wait, but let the caller decide wether the call will block |
|
|
174 | or not (for example, by coupling condition variables with some kind |
|
|
175 | of request results and supporting callbacks so the caller knows that |
|
|
176 | getting the result will not block, while still suppporting blockign |
|
|
177 | waits if the caller so desires). |
|
|
178 | |
|
|
179 | You can only wait once on a condition - additional calls will return |
168 | You can only wait once on a condition - additional calls will return |
180 | immediately. |
169 | immediately. |
|
|
170 | |
|
|
171 | Not all event models support a blocking wait - some die in that case |
|
|
172 | (programs might want to do that so they stay interactive), so *if |
|
|
173 | you are using this from a module, never require a blocking wait*, |
|
|
174 | but let the caller decide wether the call will block or not (for |
|
|
175 | example, by coupling condition variables with some kind of request |
|
|
176 | results and supporting callbacks so the caller knows that getting |
|
|
177 | the result will not block, while still suppporting blocking waits if |
|
|
178 | the caller so desires). |
|
|
179 | |
|
|
180 | Another reason *never* to "->wait" in a module is that you cannot |
|
|
181 | sensibly have two "->wait"'s in parallel, as that would require |
|
|
182 | multiple interpreters or coroutines/threads, none of which |
|
|
183 | "AnyEvent" can supply (the coroutine-aware backends "Coro::EV" and |
|
|
184 | "Coro::Event" explicitly support concurrent "->wait"'s from |
|
|
185 | different coroutines, however). |
181 | |
186 | |
182 | $cv->broadcast |
187 | $cv->broadcast |
183 | Flag the condition as ready - a running "->wait" and all further |
188 | Flag the condition as ready - a running "->wait" and all further |
184 | calls to "wait" will return after this method has been called. If |
189 | calls to "wait" will return after this method has been called. If |
185 | nobody is waiting the broadcast will be remembered.. |
190 | nobody is waiting the broadcast will be remembered.. |
… | |
… | |
228 | case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). |
233 | case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). |
229 | |
234 | |
230 | The known classes so far are: |
235 | The known classes so far are: |
231 | |
236 | |
232 | AnyEvent::Impl::CoroEV based on Coro::EV, best choice. |
237 | AnyEvent::Impl::CoroEV based on Coro::EV, best choice. |
|
|
238 | AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. |
233 | AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). |
239 | AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). |
234 | AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. |
|
|
235 | AnyEvent::Impl::Event based on Event, also second best choice :) |
240 | AnyEvent::Impl::Event based on Event, also second best choice :) |
236 | AnyEvent::Impl::Glib based on Glib, second-best choice. |
241 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
237 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
242 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
238 | AnyEvent::Impl::Perl pure-perl implementation, inefficient. |
243 | AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. |
239 | |
244 | |
240 | AnyEvent::detect |
245 | AnyEvent::detect |
241 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
246 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
242 | if necessary. You should only call this function right before you |
247 | if necessary. You should only call this function right before you |
243 | would have created an AnyEvent watcher anyway, that is, very late at |
248 | would have created an AnyEvent watcher anyway, that is, very late at |
… | |
… | |
425 | |
430 | |
426 | 1. Blocking: |
431 | 1. Blocking: |
427 | |
432 | |
428 | my $data = $fcp->client_get ($url); |
433 | my $data = $fcp->client_get ($url); |
429 | |
434 | |
430 | 2. Blocking, but parallelizing: |
435 | 2. Blocking, but running in parallel: |
431 | |
436 | |
432 | my @datas = map $_->result, |
437 | my @datas = map $_->result, |
433 | map $fcp->txn_client_get ($_), |
438 | map $fcp->txn_client_get ($_), |
434 | @urls; |
439 | @urls; |
435 | |
440 | |
436 | Both blocking examples work without the module user having to know |
441 | Both blocking examples work without the module user having to know |
437 | anything about events. |
442 | anything about events. |
438 | |
443 | |
439 | 3a. Event-based in a main program, using any support Event module: |
444 | 3a. Event-based in a main program, using any supported event module: |
440 | |
445 | |
441 | use Event; |
446 | use EV; |
442 | |
447 | |
443 | $fcp->txn_client_get ($url)->cb (sub { |
448 | $fcp->txn_client_get ($url)->cb (sub { |
444 | my $txn = shift; |
449 | my $txn = shift; |
445 | my $data = $txn->result; |
450 | my $data = $txn->result; |
446 | ... |
451 | ... |
447 | }); |
452 | }); |
448 | |
453 | |
449 | Event::loop; |
454 | EV::loop; |
450 | |
455 | |
451 | 3b. The module user could use AnyEvent, too: |
456 | 3b. The module user could use AnyEvent, too: |
452 | |
457 | |
453 | use AnyEvent; |
458 | use AnyEvent; |
454 | |
459 | |
… | |
… | |
460 | }); |
465 | }); |
461 | |
466 | |
462 | $quit->wait; |
467 | $quit->wait; |
463 | |
468 | |
464 | SEE ALSO |
469 | SEE ALSO |
465 | Event modules: Coro::Event, Coro, Event, Glib::Event, Glib. |
470 | Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, |
|
|
471 | Glib::Event, Glib, Coro, Tk. |
466 | |
472 | |
467 | Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event, |
473 | Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, |
468 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. |
474 | AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, |
|
|
475 | AnyEvent::Impl::Tk, AnyEvent::Impl::Perl. |
469 | |
476 | |
470 | Nontrivial usage example: Net::FCP. |
477 | Nontrivial usage examples: Net::FCP, Net::XMPP2. |
471 | |
478 | |
472 | |
479 | |