1 | NAME |
1 | NAME |
2 | AnyEvent - the DBI of event loop programming |
2 | AnyEvent - the DBI of event loop programming |
3 | |
3 | |
4 | EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, |
4 | EV, Event, Glib, Tk, UV, Perl, Event::Lib, Irssi, rxvt-unicode, |
5 | Qt, FLTK and POE are various supported event loops/environments. |
5 | IO::Async, Qt, FLTK and POE are various supported event |
|
|
6 | loops/environments. |
6 | |
7 | |
7 | SYNOPSIS |
8 | SYNOPSIS |
8 | use AnyEvent; |
9 | use AnyEvent; |
9 | |
10 | |
10 | # if you prefer function calls, look at the AE manpage for |
11 | # if you prefer function calls, look at the AE manpage for |
… | |
… | |
811 | $bool = $cv->ready |
812 | $bool = $cv->ready |
812 | Returns true when the condition is "true", i.e. whether "send" or |
813 | Returns true when the condition is "true", i.e. whether "send" or |
813 | "croak" have been called. |
814 | "croak" have been called. |
814 | |
815 | |
815 | $cb = $cv->cb ($cb->($cv)) |
816 | $cb = $cv->cb ($cb->($cv)) |
816 | This is a mutator function that returns the callback set and |
817 | This is a mutator function that returns the callback set (or "undef" |
817 | optionally replaces it before doing so. |
818 | if not) and optionally replaces it before doing so. |
818 | |
819 | |
819 | The callback will be called when the condition becomes "true", i.e. |
820 | The callback will be called when the condition becomes "true", i.e. |
820 | when "send" or "croak" are called, with the only argument being the |
821 | when "send" or "croak" are called, with the only argument being the |
821 | condition variable itself. If the condition is already true, the |
822 | condition variable itself. If the condition is already true, the |
822 | callback is called immediately when it is set. Calling "recv" inside |
823 | callback is called immediately when it is set. Calling "recv" inside |
823 | the callback or at any later time is guaranteed not to block. |
824 | the callback or at any later time is guaranteed not to block. |
|
|
825 | |
|
|
826 | Additionally, when the callback is invoked, it is also removed from |
|
|
827 | the condvar (reset to "undef"), so the condvar does not keep a |
|
|
828 | reference to the callback after invocation. |
824 | |
829 | |
825 | SUPPORTED EVENT LOOPS/BACKENDS |
830 | SUPPORTED EVENT LOOPS/BACKENDS |
826 | The available backend classes are (every class has its own manpage): |
831 | The available backend classes are (every class has its own manpage): |
827 | |
832 | |
828 | Backends that are autoprobed when no other event loop can be found. |
833 | Backends that are autoprobed when no other event loop can be found. |
… | |
… | |
843 | by the main program. |
848 | by the main program. |
844 | |
849 | |
845 | AnyEvent::Impl::Event based on Event, very stable, few glitches. |
850 | AnyEvent::Impl::Event based on Event, very stable, few glitches. |
846 | AnyEvent::Impl::Glib based on Glib, slow but very stable. |
851 | AnyEvent::Impl::Glib based on Glib, slow but very stable. |
847 | AnyEvent::Impl::Tk based on Tk, very broken. |
852 | AnyEvent::Impl::Tk based on Tk, very broken. |
|
|
853 | AnyEvent::Impl::UV based on UV, innovated square wheels. |
848 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
854 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
849 | AnyEvent::Impl::POE based on POE, very slow, some limitations. |
855 | AnyEvent::Impl::POE based on POE, very slow, some limitations. |
850 | AnyEvent::Impl::Irssi used when running within irssi. |
856 | AnyEvent::Impl::Irssi used when running within irssi. |
851 | AnyEvent::Impl::IOAsync based on IO::Async. |
857 | AnyEvent::Impl::IOAsync based on IO::Async. |
852 | AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. |
858 | AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. |
… | |
… | |
908 | $guard = AnyEvent::post_detect { BLOCK } |
914 | $guard = AnyEvent::post_detect { BLOCK } |
909 | Arranges for the code block to be executed as soon as the event |
915 | Arranges for the code block to be executed as soon as the event |
910 | model is autodetected (or immediately if that has already happened). |
916 | model is autodetected (or immediately if that has already happened). |
911 | |
917 | |
912 | The block will be executed *after* the actual backend has been |
918 | The block will be executed *after* the actual backend has been |
913 | detected ($AnyEvent::MODEL is set), but *before* any watchers have |
919 | detected ($AnyEvent::MODEL is set), so it is possible to do some |
914 | been created, so it is possible to e.g. patch @AnyEvent::ISA or do |
920 | initialisation only when AnyEvent is actually initialised - see the |
915 | other initialisations - see the sources of AnyEvent::Strict or |
|
|
916 | AnyEvent::AIO to see how this is used. |
921 | sources of AnyEvent::AIO to see how this is used. |
917 | |
922 | |
918 | The most common usage is to create some global watchers, without |
923 | The most common usage is to create some global watchers, without |
919 | forcing event module detection too early, for example, AnyEvent::AIO |
924 | forcing event module detection too early. For example, AnyEvent::AIO |
920 | creates and installs the global IO::AIO watcher in a "post_detect" |
925 | creates and installs the global IO::AIO watcher in a "post_detect" |
921 | block to avoid autodetecting the event module at load time. |
926 | block to avoid autodetecting the event module at load time. |
922 | |
927 | |
923 | If called in scalar or list context, then it creates and returns an |
928 | If called in scalar or list context, then it creates and returns an |
924 | object that automatically removes the callback again when it is |
929 | object that automatically removes the callback again when it is |
… | |
… | |
940 | # able to just C<undef $WATCHER> if the watcher causes them grief. |
945 | # able to just C<undef $WATCHER> if the watcher causes them grief. |
941 | |
946 | |
942 | $WATCHER ||= $guard; |
947 | $WATCHER ||= $guard; |
943 | |
948 | |
944 | @AnyEvent::post_detect |
949 | @AnyEvent::post_detect |
945 | If there are any code references in this array (you can "push" to it |
950 | This is a lower level interface then "AnyEvent::post_detect" (the |
946 | before or after loading AnyEvent), then they will be called directly |
951 | function). This variable is mainly useful for modules that can do |
|
|
952 | something useful when AnyEvent is used and thus want to know when it |
|
|
953 | is initialised, but do not need to even load it by default. This |
|
|
954 | array provides the means to hook into AnyEvent passively, without |
|
|
955 | loading it. |
|
|
956 | |
|
|
957 | Here is how it works: If there are any code references in this array |
|
|
958 | (you can "push" to it before or after loading AnyEvent), then they |
947 | after the event loop has been chosen. |
959 | will be called directly after the event loop has been chosen. |
948 | |
960 | |
949 | You should check $AnyEvent::MODEL before adding to this array, |
961 | You should check $AnyEvent::MODEL before adding to this array, |
950 | though: if it is defined then the event loop has already been |
962 | though: if it is defined then the event loop has already been |
951 | detected, and the array will be ignored. |
963 | detected, and the array will be ignored. |
952 | |
964 | |
953 | Best use "AnyEvent::post_detect { BLOCK }" when your application |
965 | Best use "AnyEvent::post_detect { BLOCK }" when your application |
954 | allows it, as it takes care of these details. |
966 | allows it, as it takes care of these details. |
955 | |
|
|
956 | This variable is mainly useful for modules that can do something |
|
|
957 | useful when AnyEvent is used and thus want to know when it is |
|
|
958 | initialised, but do not need to even load it by default. This array |
|
|
959 | provides the means to hook into AnyEvent passively, without loading |
|
|
960 | it. |
|
|
961 | |
967 | |
962 | Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used |
968 | Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used |
963 | together, you could put this into Coro (this is the actual code used |
969 | together, you could put this into Coro (this is the actual code used |
964 | by Coro to accomplish this): |
970 | by Coro to accomplish this): |
965 | |
971 | |
… | |
… | |
984 | To understand the usefulness of this function, consider a function |
990 | To understand the usefulness of this function, consider a function |
985 | that asynchronously does something for you and returns some |
991 | that asynchronously does something for you and returns some |
986 | transaction object or guard to let you cancel the operation. For |
992 | transaction object or guard to let you cancel the operation. For |
987 | example, "AnyEvent::Socket::tcp_connect": |
993 | example, "AnyEvent::Socket::tcp_connect": |
988 | |
994 | |
989 | # start a conenction attempt unless one is active |
995 | # start a connection attempt unless one is active |
990 | $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { |
996 | $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { |
991 | delete $self->{connect_guard}; |
997 | delete $self->{connect_guard}; |
992 | ... |
998 | ... |
993 | }; |
999 | }; |
994 | |
1000 | |
… | |
… | |
1028 | If you want to sprinkle loads of logging calls around your code, |
1034 | If you want to sprinkle loads of logging calls around your code, |
1029 | consider creating a logger callback with the "AnyEvent::Log::logger" |
1035 | consider creating a logger callback with the "AnyEvent::Log::logger" |
1030 | function, which can reduce typing, codesize and can reduce the |
1036 | function, which can reduce typing, codesize and can reduce the |
1031 | logging overhead enourmously. |
1037 | logging overhead enourmously. |
1032 | |
1038 | |
|
|
1039 | AnyEvent::fh_block $filehandle |
|
|
1040 | AnyEvent::fh_unblock $filehandle |
|
|
1041 | Sets blocking or non-blocking behaviour for the given filehandle. |
|
|
1042 | |
1033 | WHAT TO DO IN A MODULE |
1043 | WHAT TO DO IN A MODULE |
1034 | As a module author, you should "use AnyEvent" and call AnyEvent methods |
1044 | As a module author, you should "use AnyEvent" and call AnyEvent methods |
1035 | freely, but you should not load a specific event module or rely on it. |
1045 | freely, but you should not load a specific event module or rely on it. |
1036 | |
1046 | |
1037 | Be careful when you create watchers in the module body - AnyEvent will |
1047 | Be careful when you create watchers in the module body - AnyEvent will |
… | |
… | |
1358 | mentioned will be used, and preference will be given to protocols |
1368 | mentioned will be used, and preference will be given to protocols |
1359 | mentioned earlier in the list. |
1369 | mentioned earlier in the list. |
1360 | |
1370 | |
1361 | This variable can effectively be used for denial-of-service attacks |
1371 | This variable can effectively be used for denial-of-service attacks |
1362 | against local programs (e.g. when setuid), although the impact is |
1372 | against local programs (e.g. when setuid), although the impact is |
1363 | likely small, as the program has to handle conenction and other |
1373 | likely small, as the program has to handle connection and other |
1364 | failures anyways. |
1374 | failures anyways. |
1365 | |
1375 | |
1366 | Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over |
1376 | Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over |
1367 | IPv6, but support both and try to use both. |
1377 | IPv6, but support both and try to use both. |
1368 | "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to |
1378 | "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to |
… | |
… | |
1602 | my $txn = shift; |
1612 | my $txn = shift; |
1603 | my $data = $txn->result; |
1613 | my $data = $txn->result; |
1604 | ... |
1614 | ... |
1605 | }); |
1615 | }); |
1606 | |
1616 | |
1607 | EV::loop; |
1617 | EV::run; |
1608 | |
1618 | |
1609 | 3b. The module user could use AnyEvent, too: |
1619 | 3b. The module user could use AnyEvent, too: |
1610 | |
1620 | |
1611 | use AnyEvent; |
1621 | use AnyEvent; |
1612 | |
1622 | |
… | |
… | |
2119 | |
2129 | |
2120 | Development/Debugging: AnyEvent::Strict (stricter checking), |
2130 | Development/Debugging: AnyEvent::Strict (stricter checking), |
2121 | AnyEvent::Debug (interactive shell, watcher tracing). |
2131 | AnyEvent::Debug (interactive shell, watcher tracing). |
2122 | |
2132 | |
2123 | Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, |
2133 | Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, |
2124 | Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK. |
2134 | Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV. |
2125 | |
2135 | |
2126 | Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, |
2136 | Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, |
2127 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, |
2137 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, |
2128 | AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, |
2138 | AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, |
2129 | AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK. |
2139 | AnyEvent::Impl::IOAsync, AnyEvent::Impl::Irssi, AnyEvent::Impl::FLTK, |
|
|
2140 | AnyEvent::Impl::Cocoa, AnyEvent::Impl::UV. |
2130 | |
2141 | |
2131 | Non-blocking handles, pipes, stream sockets, TCP clients and servers: |
2142 | Non-blocking handles, pipes, stream sockets, TCP clients and servers: |
2132 | AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. |
2143 | AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. |
2133 | |
2144 | |
2134 | Asynchronous File I/O: AnyEvent::IO. |
2145 | Asynchronous File I/O: AnyEvent::IO. |