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 |
… | |
… | |
469 | |
470 | |
470 | Example: fork a process and wait for it |
471 | Example: fork a process and wait for it |
471 | |
472 | |
472 | my $done = AnyEvent->condvar; |
473 | my $done = AnyEvent->condvar; |
473 | |
474 | |
|
|
475 | # this forks and immediately calls exit in the child. this |
|
|
476 | # normally has all sorts of bad consequences for your parent, |
|
|
477 | # so take this as an example only. always fork and exec, |
|
|
478 | # or call POSIX::_exit, in real code. |
474 | my $pid = fork or exit 5; |
479 | my $pid = fork or exit 5; |
475 | |
480 | |
476 | my $w = AnyEvent->child ( |
481 | my $w = AnyEvent->child ( |
477 | pid => $pid, |
482 | pid => $pid, |
478 | cb => sub { |
483 | cb => sub { |
… | |
… | |
718 | This works because for every event source (EOF on file handle), |
723 | This works because for every event source (EOF on file handle), |
719 | there is one call to "begin", so the condvar waits for all calls to |
724 | there is one call to "begin", so the condvar waits for all calls to |
720 | "end" before sending. |
725 | "end" before sending. |
721 | |
726 | |
722 | The ping example mentioned above is slightly more complicated, as |
727 | The ping example mentioned above is slightly more complicated, as |
723 | the there are results to be passwd back, and the number of tasks |
728 | the there are results to be passed back, and the number of tasks |
724 | that are begun can potentially be zero: |
729 | that are begun can potentially be zero: |
725 | |
730 | |
726 | my $cv = AnyEvent->condvar; |
731 | my $cv = AnyEvent->condvar; |
727 | |
732 | |
728 | my %result; |
733 | my %result; |
… | |
… | |
839 | by the main program. |
844 | by the main program. |
840 | |
845 | |
841 | AnyEvent::Impl::Event based on Event, very stable, few glitches. |
846 | AnyEvent::Impl::Event based on Event, very stable, few glitches. |
842 | AnyEvent::Impl::Glib based on Glib, slow but very stable. |
847 | AnyEvent::Impl::Glib based on Glib, slow but very stable. |
843 | AnyEvent::Impl::Tk based on Tk, very broken. |
848 | AnyEvent::Impl::Tk based on Tk, very broken. |
|
|
849 | AnyEvent::Impl::UV based on UV, innovated square wheels. |
844 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
850 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
845 | AnyEvent::Impl::POE based on POE, very slow, some limitations. |
851 | AnyEvent::Impl::POE based on POE, very slow, some limitations. |
846 | AnyEvent::Impl::Irssi used when running within irssi. |
852 | AnyEvent::Impl::Irssi used when running within irssi. |
847 | AnyEvent::Impl::IOAsync based on IO::Async. |
853 | AnyEvent::Impl::IOAsync based on IO::Async. |
848 | AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. |
854 | AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. |
… | |
… | |
980 | To understand the usefulness of this function, consider a function |
986 | To understand the usefulness of this function, consider a function |
981 | that asynchronously does something for you and returns some |
987 | that asynchronously does something for you and returns some |
982 | transaction object or guard to let you cancel the operation. For |
988 | transaction object or guard to let you cancel the operation. For |
983 | example, "AnyEvent::Socket::tcp_connect": |
989 | example, "AnyEvent::Socket::tcp_connect": |
984 | |
990 | |
985 | # start a conenction attempt unless one is active |
991 | # start a connection attempt unless one is active |
986 | $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { |
992 | $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { |
987 | delete $self->{connect_guard}; |
993 | delete $self->{connect_guard}; |
988 | ... |
994 | ... |
989 | }; |
995 | }; |
990 | |
996 | |
… | |
… | |
1024 | If you want to sprinkle loads of logging calls around your code, |
1030 | If you want to sprinkle loads of logging calls around your code, |
1025 | consider creating a logger callback with the "AnyEvent::Log::logger" |
1031 | consider creating a logger callback with the "AnyEvent::Log::logger" |
1026 | function, which can reduce typing, codesize and can reduce the |
1032 | function, which can reduce typing, codesize and can reduce the |
1027 | logging overhead enourmously. |
1033 | logging overhead enourmously. |
1028 | |
1034 | |
|
|
1035 | AnyEvent::fh_block $filehandle |
|
|
1036 | AnyEvent::fh_unblock $filehandle |
|
|
1037 | Sets blocking or non-blocking behaviour for the given filehandle. |
|
|
1038 | |
1029 | WHAT TO DO IN A MODULE |
1039 | WHAT TO DO IN A MODULE |
1030 | As a module author, you should "use AnyEvent" and call AnyEvent methods |
1040 | As a module author, you should "use AnyEvent" and call AnyEvent methods |
1031 | freely, but you should not load a specific event module or rely on it. |
1041 | freely, but you should not load a specific event module or rely on it. |
1032 | |
1042 | |
1033 | Be careful when you create watchers in the module body - AnyEvent will |
1043 | Be careful when you create watchers in the module body - AnyEvent will |
… | |
… | |
1120 | AnyEvent::AIO (part of the AnyEvent distribution) |
1130 | AnyEvent::AIO (part of the AnyEvent distribution) |
1121 | Truly asynchronous (as opposed to non-blocking) I/O, should be in |
1131 | Truly asynchronous (as opposed to non-blocking) I/O, should be in |
1122 | the toolbox of every event programmer. AnyEvent::AIO transparently |
1132 | the toolbox of every event programmer. AnyEvent::AIO transparently |
1123 | fuses IO::AIO and AnyEvent together, giving AnyEvent access to |
1133 | fuses IO::AIO and AnyEvent together, giving AnyEvent access to |
1124 | event-based file I/O, and much more. |
1134 | event-based file I/O, and much more. |
|
|
1135 | |
|
|
1136 | AnyEvent::Fork, AnyEvent::Fork::RPC, AnyEvent::Fork::Pool, |
|
|
1137 | AnyEvent::Fork::Remote |
|
|
1138 | These let you safely fork new subprocesses, either locally or |
|
|
1139 | remotely (e.g.v ia ssh), using some RPC protocol or not, without the |
|
|
1140 | limitations normally imposed by fork (AnyEvent works fine for |
|
|
1141 | example). Dynamically-resized worker pools are obviously included as |
|
|
1142 | well. |
|
|
1143 | |
|
|
1144 | And they are quite tiny and fast as well - "abusing" AnyEvent::Fork |
|
|
1145 | just to exec external programs can easily beat using "fork" and |
|
|
1146 | "exec" (or even "system") in most programs. |
1125 | |
1147 | |
1126 | AnyEvent::Filesys::Notify |
1148 | AnyEvent::Filesys::Notify |
1127 | AnyEvent is good for non-blocking stuff, but it can't detect file or |
1149 | AnyEvent is good for non-blocking stuff, but it can't detect file or |
1128 | path changes (e.g. "watch this directory for new files", "watch this |
1150 | path changes (e.g. "watch this directory for new files", "watch this |
1129 | file for changes"). The AnyEvent::Filesys::Notify module promises to |
1151 | file for changes"). The AnyEvent::Filesys::Notify module promises to |
… | |
… | |
1131 | and some weird, without doubt broken, stuff on OS X to monitor |
1153 | and some weird, without doubt broken, stuff on OS X to monitor |
1132 | files. It can fall back to blocking scans at regular intervals |
1154 | files. It can fall back to blocking scans at regular intervals |
1133 | transparently on other platforms, so it's about as portable as it |
1155 | transparently on other platforms, so it's about as portable as it |
1134 | gets. |
1156 | gets. |
1135 | |
1157 | |
1136 | (I haven't used it myself, but I haven't heard anybody complaining |
1158 | (I haven't used it myself, but it seems the biggest problem with it |
1137 | about it yet). |
1159 | is it quite bad performance). |
1138 | |
1160 | |
1139 | AnyEvent::DBI |
1161 | AnyEvent::DBI |
1140 | Executes DBI requests asynchronously in a proxy process for you, |
1162 | Executes DBI requests asynchronously in a proxy process for you, |
1141 | notifying you in an event-based way when the operation is finished. |
1163 | notifying you in an event-based way when the operation is finished. |
1142 | |
|
|
1143 | AnyEvent::HTTPD |
|
|
1144 | A simple embedded webserver. |
|
|
1145 | |
1164 | |
1146 | AnyEvent::FastPing |
1165 | AnyEvent::FastPing |
1147 | The fastest ping in the west. |
1166 | The fastest ping in the west. |
1148 | |
1167 | |
1149 | Coro |
1168 | Coro |
… | |
… | |
1345 | mentioned will be used, and preference will be given to protocols |
1364 | mentioned will be used, and preference will be given to protocols |
1346 | mentioned earlier in the list. |
1365 | mentioned earlier in the list. |
1347 | |
1366 | |
1348 | This variable can effectively be used for denial-of-service attacks |
1367 | This variable can effectively be used for denial-of-service attacks |
1349 | against local programs (e.g. when setuid), although the impact is |
1368 | against local programs (e.g. when setuid), although the impact is |
1350 | likely small, as the program has to handle conenction and other |
1369 | likely small, as the program has to handle connection and other |
1351 | failures anyways. |
1370 | failures anyways. |
1352 | |
1371 | |
1353 | Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over |
1372 | Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over |
1354 | IPv6, but support both and try to use both. |
1373 | IPv6, but support both and try to use both. |
1355 | "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to |
1374 | "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to |
… | |
… | |
2035 | usually happens when the first AnyEvent watcher is created, or the |
2054 | usually happens when the first AnyEvent watcher is created, or the |
2036 | library is loaded). |
2055 | library is loaded). |
2037 | |
2056 | |
2038 | If you have to fork, you must either do so *before* creating your first |
2057 | If you have to fork, you must either do so *before* creating your first |
2039 | watcher OR you must not use AnyEvent at all in the child OR you must do |
2058 | watcher OR you must not use AnyEvent at all in the child OR you must do |
2040 | something completely out of the scope of AnyEvent. |
2059 | something completely out of the scope of AnyEvent (see below). |
2041 | |
2060 | |
2042 | The problem of doing event processing in the parent *and* the child is |
2061 | The problem of doing event processing in the parent *and* the child is |
2043 | much more complicated: even for backends that *are* fork-aware or |
2062 | much more complicated: even for backends that *are* fork-aware or |
2044 | fork-safe, their behaviour is not usually what you want: fork clones all |
2063 | fork-safe, their behaviour is not usually what you want: fork clones all |
2045 | watchers, that means all timers, I/O watchers etc. are active in both |
2064 | watchers, that means all timers, I/O watchers etc. are active in both |
2046 | parent and child, which is almost never what you want. USing "exec" to |
2065 | parent and child, which is almost never what you want. Using "exec" to |
2047 | start worker children from some kind of manage rprocess is usually |
2066 | start worker children from some kind of manage prrocess is usually |
2048 | preferred, because it is much easier and cleaner, at the expense of |
2067 | preferred, because it is much easier and cleaner, at the expense of |
2049 | having to have another binary. |
2068 | having to have another binary. |
|
|
2069 | |
|
|
2070 | In addition to logical problems with fork, there are also implementation |
|
|
2071 | problems. For example, on POSIX systems, you cannot fork at all in Perl |
|
|
2072 | code if a thread (I am talking of pthreads here) was ever created in the |
|
|
2073 | process, and this is just the tip of the iceberg. In general, using fork |
|
|
2074 | from Perl is difficult, and attempting to use fork without an exec to |
|
|
2075 | implement some kind of parallel processing is almost certainly doomed. |
|
|
2076 | |
|
|
2077 | To safely fork and exec, you should use a module such as Proc::FastSpawn |
|
|
2078 | that let's you safely fork and exec new processes. |
|
|
2079 | |
|
|
2080 | If you want to do multiprocessing using processes, you can look at the |
|
|
2081 | AnyEvent::Fork module (and some related modules such as |
|
|
2082 | AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote). |
|
|
2083 | This module allows you to safely create subprocesses without any |
|
|
2084 | limitations - you can use X11 toolkits or AnyEvent in the children |
|
|
2085 | created by AnyEvent::Fork safely and without any special precautions. |
2050 | |
2086 | |
2051 | SECURITY CONSIDERATIONS |
2087 | SECURITY CONSIDERATIONS |
2052 | AnyEvent can be forced to load any event model via |
2088 | AnyEvent can be forced to load any event model via |
2053 | $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used |
2089 | $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used |
2054 | to execute arbitrary code or directly gain access, it can easily be used |
2090 | to execute arbitrary code or directly gain access, it can easily be used |
… | |
… | |
2089 | |
2125 | |
2090 | Development/Debugging: AnyEvent::Strict (stricter checking), |
2126 | Development/Debugging: AnyEvent::Strict (stricter checking), |
2091 | AnyEvent::Debug (interactive shell, watcher tracing). |
2127 | AnyEvent::Debug (interactive shell, watcher tracing). |
2092 | |
2128 | |
2093 | Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, |
2129 | Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, |
2094 | Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK. |
2130 | Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV. |
2095 | |
2131 | |
2096 | Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, |
2132 | Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, |
2097 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, |
2133 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, |
2098 | AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, |
2134 | AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, |
2099 | AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK. |
2135 | AnyEvent::Impl::IOAsync, AnyEvent::Impl::Irssi, AnyEvent::Impl::FLTK, |
|
|
2136 | AnyEvent::Impl::Cocoa, AnyEvent::Impl::UV. |
2100 | |
2137 | |
2101 | Non-blocking handles, pipes, stream sockets, TCP clients and servers: |
2138 | Non-blocking handles, pipes, stream sockets, TCP clients and servers: |
2102 | AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. |
2139 | AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. |
2103 | |
2140 | |
2104 | Asynchronous File I/O: AnyEvent::IO. |
2141 | Asynchronous File I/O: AnyEvent::IO. |