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

Comparing AnyEvent/README (file contents):
Revision 1.66 by root, Sun Aug 21 03:02:32 2011 UTC vs.
Revision 1.77 by root, Sat Sep 17 02:33:54 2016 UTC

1NAME 1NAME
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
7SYNOPSIS 8SYNOPSIS
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
… …
262 263
263 Example 2: fire an event after 0.5 seconds, then roughly every second. 264 Example 2: fire an event after 0.5 seconds, then roughly every second.
264 265
265 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { 266 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
266 warn "timeout\n"; 267 warn "timeout\n";
267 }; 268 });
268 269
269 TIMING ISSUES 270 TIMING ISSUES
270 There are two ways to handle timers: based on real time (relative, "fire 271 There are two ways to handle timers: based on real time (relative, "fire
271 in 10 seconds") and based on wallclock time (absolute, "fire at 12 272 in 10 seconds") and based on wallclock time (absolute, "fire at 12
272 o'clock"). 273 o'clock").
… …
403 will not restart syscalls (that includes Async::Interrupt and AnyEvent's 404 will not restart syscalls (that includes Async::Interrupt and AnyEvent's
404 pure perl implementation). 405 pure perl implementation).
405 406
406 Safe/Unsafe Signals 407 Safe/Unsafe Signals
407 Perl signals can be either "safe" (synchronous to opcode handling) or 408 Perl signals can be either "safe" (synchronous to opcode handling) or
408 "unsafe" (asynchronous) - the former might get delayed indefinitely, the 409 "unsafe" (asynchronous) - the former might delay signal delivery
409 latter might corrupt your memory. 410 indefinitely, the latter might corrupt your memory.
410 411
411 AnyEvent signal handlers are, in addition, synchronous to the event 412 AnyEvent signal handlers are, in addition, synchronous to the event
412 loop, i.e. they will not interrupt your running perl program but will 413 loop, i.e. they will not interrupt your running perl program but will
413 only be called as part of the normal event handling (just like timer, 414 only be called as part of the normal event handling (just like timer,
414 I/O etc. callbacks, too). 415 I/O etc. callbacks, too).
… …
416 Signal Races, Delays and Workarounds 417 Signal Races, Delays and Workarounds
417 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 418 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
418 callbacks to signals in a generic way, which is a pity, as you cannot do 419 callbacks to signals in a generic way, which is a pity, as you cannot do
419 race-free signal handling in perl, requiring C libraries for this. 420 race-free signal handling in perl, requiring C libraries for this.
420 AnyEvent will try to do its best, which means in some cases, signals 421 AnyEvent will try to do its best, which means in some cases, signals
421 will be delayed. The maximum time a signal might be delayed is specified 422 will be delayed. The maximum time a signal might be delayed is 10
422 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable 423 seconds by default, but can be overriden via
423 can be changed only before the first signal watcher is created, and 424 $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} or $AnyEvent::MAX_SIGNAL_LATENCY
424 should be left alone otherwise. This variable determines how often 425 - see the "ENVIRONMENT VARIABLES" section for details.
425 AnyEvent polls for signals (in case a wake-up was missed). Higher values
426 will cause fewer spurious wake-ups, which is better for power and CPU
427 saving.
428 426
429 All these problems can be avoided by installing the optional 427 All these problems can be avoided by installing the optional
430 Async::Interrupt module, which works with most event loops. It will not 428 Async::Interrupt module, which works with most event loops. It will not
431 work with inherently broken event loops such as Event or Event::Lib (and 429 work with inherently broken event loops such as Event or Event::Lib (and
432 not with POE currently, as POE does its own workaround with one-second
433 latency). For those, you just have to suffer the delays. 430 not with POE currently). For those, you just have to suffer the delays.
434 431
435 CHILD PROCESS WATCHERS 432 CHILD PROCESS WATCHERS
436 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 433 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
437 434
438 You can also watch for a child process exit and catch its exit status. 435 You can also watch for a child process exit and catch its exit status.
… …
473 470
474 Example: fork a process and wait for it 471 Example: fork a process and wait for it
475 472
476 my $done = AnyEvent->condvar; 473 my $done = AnyEvent->condvar;
477 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.
478 my $pid = fork or exit 5; 479 my $pid = fork or exit 5;
479 480
480 my $w = AnyEvent->child ( 481 my $w = AnyEvent->child (
481 pid => $pid, 482 pid => $pid,
482 cb => sub { 483 cb => sub {
… …
722 This works because for every event source (EOF on file handle), 723 This works because for every event source (EOF on file handle),
723 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
724 "end" before sending. 725 "end" before sending.
725 726
726 The ping example mentioned above is slightly more complicated, as 727 The ping example mentioned above is slightly more complicated, as
727 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
728 that are begun can potentially be zero: 729 that are begun can potentially be zero:
729 730
730 my $cv = AnyEvent->condvar; 731 my $cv = AnyEvent->condvar;
731 732
732 my %result; 733 my %result;
… …
740 }; 741 };
741 } 742 }
742 743
743 $cv->end; 744 $cv->end;
744 745
746 ...
747
748 my $results = $cv->recv;
749
745 This code fragment supposedly pings a number of hosts and calls 750 This code fragment supposedly pings a number of hosts and calls
746 "send" after results for all then have have been gathered - in any 751 "send" after results for all then have have been gathered - in any
747 order. To achieve this, the code issues a call to "begin" when it 752 order. To achieve this, the code issues a call to "begin" when it
748 starts each ping request and calls "end" when it has received some 753 starts each ping request and calls "end" when it has received some
749 result for it. Since "begin" and "end" only maintain a counter, the 754 result for it. Since "begin" and "end" only maintain a counter, the
… …
778 In list context, all parameters passed to "send" will be returned, 783 In list context, all parameters passed to "send" will be returned,
779 in scalar context only the first one will be returned. 784 in scalar context only the first one will be returned.
780 785
781 Note that doing a blocking wait in a callback is not supported by 786 Note that doing a blocking wait in a callback is not supported by
782 any event loop, that is, recursive invocation of a blocking "->recv" 787 any event loop, that is, recursive invocation of a blocking "->recv"
783 is not allowed, and the "recv" call will "croak" if such a condition 788 is not allowed and the "recv" call will "croak" if such a condition
784 is detected. This condition can be slightly loosened by using 789 is detected. This requirement can be dropped by relying on
785 Coro::AnyEvent, which allows you to do a blocking "->recv" from any 790 Coro::AnyEvent , which allows you to do a blocking "->recv" from any
786 thread that doesn't run the event loop itself. 791 thread that doesn't run the event loop itself. Coro::AnyEvent is
792 loaded automatically when Coro is used with AnyEvent, so code does
793 not need to do anything special to take advantage of that: any code
794 that would normally block your program because it calls "recv", be
795 executed in an "async" thread instead without blocking other
796 threads.
787 797
788 Not all event models support a blocking wait - some die in that case 798 Not all event models support a blocking wait - some die in that case
789 (programs might want to do that to stay interactive), so *if you are 799 (programs might want to do that to stay interactive), so *if you are
790 using this from a module, never require a blocking wait*. Instead, 800 using this from a module, never require a blocking wait*. Instead,
791 let the caller decide whether the call will block or not (for 801 let the caller decide whether the call will block or not (for
… …
802 $bool = $cv->ready 812 $bool = $cv->ready
803 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
804 "croak" have been called. 814 "croak" have been called.
805 815
806 $cb = $cv->cb ($cb->($cv)) 816 $cb = $cv->cb ($cb->($cv))
807 This is a mutator function that returns the callback set and 817 This is a mutator function that returns the callback set (or "undef"
808 optionally replaces it before doing so. 818 if not) and optionally replaces it before doing so.
809 819
810 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.
811 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
812 condition variable itself. If the condition is already true, the 822 condition variable itself. If the condition is already true, the
813 callback is called immediately when it is set. Calling "recv" inside 823 callback is called immediately when it is set. Calling "recv" inside
814 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.
815 829
816SUPPORTED EVENT LOOPS/BACKENDS 830SUPPORTED EVENT LOOPS/BACKENDS
817 The available backend classes are (every class has its own manpage): 831 The available backend classes are (every class has its own manpage):
818 832
819 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.
… …
834 by the main program. 848 by the main program.
835 849
836 AnyEvent::Impl::Event based on Event, very stable, few glitches. 850 AnyEvent::Impl::Event based on Event, very stable, few glitches.
837 AnyEvent::Impl::Glib based on Glib, slow but very stable. 851 AnyEvent::Impl::Glib based on Glib, slow but very stable.
838 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.
839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 854 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
840 AnyEvent::Impl::POE based on POE, very slow, some limitations. 855 AnyEvent::Impl::POE based on POE, very slow, some limitations.
841 AnyEvent::Impl::Irssi used when running within irssi. 856 AnyEvent::Impl::Irssi used when running within irssi.
842 AnyEvent::Impl::IOAsync based on IO::Async. 857 AnyEvent::Impl::IOAsync based on IO::Async.
843 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 858 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
844 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 859 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
845 860
846 Backends with special needs. 861 Backends with special needs.
847 Qt requires the Qt::Application to be instantiated first, but will 862 Qt requires the Qt::Application to be instantiated first, but will
848 otherwise be picked up automatically. As long as the main program 863 otherwise be picked up automatically. As long as the main program
849 instantiates the application before any AnyEvent watchers are 864 instantiates the application before any AnyEvent watchers are
… …
975 To understand the usefulness of this function, consider a function 990 To understand the usefulness of this function, consider a function
976 that asynchronously does something for you and returns some 991 that asynchronously does something for you and returns some
977 transaction object or guard to let you cancel the operation. For 992 transaction object or guard to let you cancel the operation. For
978 example, "AnyEvent::Socket::tcp_connect": 993 example, "AnyEvent::Socket::tcp_connect":
979 994
980 # start a conenction attempt unless one is active 995 # start a connection attempt unless one is active
981 $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 {
982 delete $self->{connect_guard}; 997 delete $self->{connect_guard};
983 ... 998 ...
984 }; 999 };
985 1000
… …
1005 if $some_error_condition; 1020 if $some_error_condition;
1006 1021
1007 AnyEvent::log $level, $msg[, @args] 1022 AnyEvent::log $level, $msg[, @args]
1008 Log the given $msg at the given $level. 1023 Log the given $msg at the given $level.
1009 1024
1025 If AnyEvent::Log is not loaded then this function makes a simple
1026 test to see whether the message will be logged. If the test succeeds
1010 Loads AnyEvent::Log on first use and calls "AnyEvent::Log::log" - 1027 it will load AnyEvent::Log and call "AnyEvent::Log::log" -
1011 consequently, look at the AnyEvent::Log documentation for details. 1028 consequently, look at the AnyEvent::Log documentation for details.
1029
1030 If the test fails it will simply return. Right now this happens when
1031 a numerical loglevel is used and it is larger than the level
1032 specified via $ENV{PERL_ANYEVENT_VERBOSE}.
1012 1033
1013 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,
1014 consider creating a logger callback with the "AnyEvent::Log::logger" 1035 consider creating a logger callback with the "AnyEvent::Log::logger"
1015 function. 1036 function, which can reduce typing, codesize and can reduce the
1037 logging overhead enourmously.
1038
1039 AnyEvent::fh_block $filehandle
1040 AnyEvent::fh_unblock $filehandle
1041 Sets blocking or non-blocking behaviour for the given filehandle.
1016 1042
1017WHAT TO DO IN A MODULE 1043WHAT TO DO IN A MODULE
1018 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
1019 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.
1020 1046
… …
1079 modules come as part of AnyEvent, the others are available via CPAN (see 1105 modules come as part of AnyEvent, the others are available via CPAN (see
1080 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer 1106 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer
1081 non-exhaustive list), and the list is heavily biased towards modules of 1107 non-exhaustive list), and the list is heavily biased towards modules of
1082 the AnyEvent author himself :) 1108 the AnyEvent author himself :)
1083 1109
1084 AnyEvent::Util 1110 AnyEvent::Util (part of the AnyEvent distribution)
1085 Contains various utility functions that replace often-used blocking 1111 Contains various utility functions that replace often-used blocking
1086 functions such as "inet_aton" with event/callback-based versions. 1112 functions such as "inet_aton" with event/callback-based versions.
1087 1113
1088 AnyEvent::Socket 1114 AnyEvent::Socket (part of the AnyEvent distribution)
1089 Provides various utility functions for (internet protocol) sockets, 1115 Provides various utility functions for (internet protocol) sockets,
1090 addresses and name resolution. Also functions to create non-blocking 1116 addresses and name resolution. Also functions to create non-blocking
1091 tcp connections or tcp servers, with IPv6 and SRV record support and 1117 tcp connections or tcp servers, with IPv6 and SRV record support and
1092 more. 1118 more.
1093 1119
1094 AnyEvent::Handle 1120 AnyEvent::Handle (part of the AnyEvent distribution)
1095 Provide read and write buffers, manages watchers for reads and 1121 Provide read and write buffers, manages watchers for reads and
1096 writes, supports raw and formatted I/O, I/O queued and fully 1122 writes, supports raw and formatted I/O, I/O queued and fully
1097 transparent and non-blocking SSL/TLS (via AnyEvent::TLS). 1123 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1098 1124
1099 AnyEvent::DNS 1125 AnyEvent::DNS (part of the AnyEvent distribution)
1100 Provides rich asynchronous DNS resolver capabilities. 1126 Provides rich asynchronous DNS resolver capabilities.
1101 1127
1102 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1128 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1103 AnyEvent::IGS, AnyEvent::FCP 1129 AnyEvent::IGS, AnyEvent::FCP
1104 Implement event-based interfaces to the protocols of the same name 1130 Implement event-based interfaces to the protocols of the same name
1105 (for the curious, IGS is the International Go Server and FCP is the 1131 (for the curious, IGS is the International Go Server and FCP is the
1106 Freenet Client Protocol). 1132 Freenet Client Protocol).
1107 1133
1108 AnyEvent::Handle::UDP 1134 AnyEvent::AIO (part of the AnyEvent distribution)
1109 Here be danger!
1110
1111 As Pauli would put it, "Not only is it not right, it's not even
1112 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
1113 most notably its use of a stream-based API with a protocol that
1114 isn't streamable, that the only way to improve it is to delete it.
1115
1116 It features data corruption (but typically only under load) and
1117 general confusion. On top, the author is not only clueless about UDP
1118 but also fact-resistant - some gems of his understanding: "connect
1119 doesn't work with UDP", "UDP packets are not IP packets", "UDP only
1120 has datagrams, not packets", "I don't need to implement proper error
1121 checking as UDP doesn't support error checking" and so on - he
1122 doesn't even understand what's wrong with his module when it is
1123 explained to him.
1124
1125 AnyEvent::DBI
1126 Executes DBI requests asynchronously in a proxy process for you,
1127 notifying you in an event-based way when the operation is finished.
1128
1129 AnyEvent::AIO
1130 Truly asynchronous (as opposed to non-blocking) I/O, should be in 1135 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1131 the toolbox of every event programmer. AnyEvent::AIO transparently 1136 the toolbox of every event programmer. AnyEvent::AIO transparently
1132 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1137 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1133 event-based file I/O, and much more. 1138 event-based file I/O, and much more.
1134 1139
1140 AnyEvent::Fork, AnyEvent::Fork::RPC, AnyEvent::Fork::Pool,
1141 AnyEvent::Fork::Remote
1142 These let you safely fork new subprocesses, either locally or
1143 remotely (e.g.v ia ssh), using some RPC protocol or not, without the
1144 limitations normally imposed by fork (AnyEvent works fine for
1145 example). Dynamically-resized worker pools are obviously included as
1146 well.
1147
1148 And they are quite tiny and fast as well - "abusing" AnyEvent::Fork
1149 just to exec external programs can easily beat using "fork" and
1150 "exec" (or even "system") in most programs.
1151
1152 AnyEvent::Filesys::Notify
1153 AnyEvent is good for non-blocking stuff, but it can't detect file or
1154 path changes (e.g. "watch this directory for new files", "watch this
1155 file for changes"). The AnyEvent::Filesys::Notify module promises to
1156 do just that in a portbale fashion, supporting inotify on GNU/Linux
1157 and some weird, without doubt broken, stuff on OS X to monitor
1158 files. It can fall back to blocking scans at regular intervals
1159 transparently on other platforms, so it's about as portable as it
1160 gets.
1161
1162 (I haven't used it myself, but it seems the biggest problem with it
1163 is it quite bad performance).
1164
1135 AnyEvent::HTTPD 1165 AnyEvent::DBI
1136 A simple embedded webserver. 1166 Executes DBI requests asynchronously in a proxy process for you,
1167 notifying you in an event-based way when the operation is finished.
1137 1168
1138 AnyEvent::FastPing 1169 AnyEvent::FastPing
1139 The fastest ping in the west. 1170 The fastest ping in the west.
1140 1171
1141 Coro 1172 Coro
1142 Has special support for AnyEvent via Coro::AnyEvent. 1173 Has special support for AnyEvent via Coro::AnyEvent, which allows
1174 you to simply invert the flow control - don't call us, we will call
1175 you:
1176
1177 async {
1178 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1179 print "5 seconds later!\n";
1180
1181 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1182 my $line = <STDIN>; # works for ttys
1183
1184 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1185 my ($body, $hdr) = Coro::rouse_wait;
1186 };
1143 1187
1144SIMPLIFIED AE API 1188SIMPLIFIED AE API
1145 Starting with version 5.0, AnyEvent officially supports a second, much 1189 Starting with version 5.0, AnyEvent officially supports a second, much
1146 simpler, API that is designed to reduce the calling, typing and memory 1190 simpler, API that is designed to reduce the calling, typing and memory
1147 overhead by using function call syntax and a fixed number of parameters. 1191 overhead by using function call syntax and a fixed number of parameters.
… …
1163 The pure perl event loop simply re-throws the exception (usually within 1207 The pure perl event loop simply re-throws the exception (usually within
1164 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 1208 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1165 Glib uses "install_exception_handler" and so on. 1209 Glib uses "install_exception_handler" and so on.
1166 1210
1167ENVIRONMENT VARIABLES 1211ENVIRONMENT VARIABLES
1168 The following environment variables are used by this module or its 1212 AnyEvent supports a number of environment variables that tune the
1169 submodules. 1213 runtime behaviour. They are usually evaluated when AnyEvent is loaded,
1214 initialised, or a submodule that uses them is loaded. Many of them also
1215 cause AnyEvent to load additional modules - for example,
1216 "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be
1217 loaded.
1170 1218
1171 Note that AnyEvent will remove *all* environment variables starting with 1219 All the environment variables documented here start with
1172 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is 1220 "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace.
1173 enabled. 1221 Other modules are encouraged (but by no means required) to use
1222 "PERL_ANYEVENT_SUBMODULE" if they have registered the
1223 AnyEvent::Submodule namespace on CPAN, for any submodule. For example,
1224 AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it
1225 should not access env variables starting with "AE_", see below).
1226
1227 All variables can also be set via the "AE_" prefix, that is, instead of
1228 setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case
1229 there is a clash btween anyevent and another program that uses
1230 "AE_something" you can set the corresponding "PERL_ANYEVENT_something"
1231 variable to the empty string, as those variables take precedence.
1232
1233 When AnyEvent is first loaded, it copies all "AE_xxx" env variables to
1234 their "PERL_ANYEVENT_xxx" counterpart unless that variable already
1235 exists. If taint mode is on, then AnyEvent will remove *all* environment
1236 variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with
1237 "undef" or the empty string, if the corresaponding "AE_" variable is
1238 set).
1239
1240 The exact algorithm is currently:
1241
1242 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
1243 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
1244 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
1245
1246 This ensures that child processes will not see the "AE_" variables.
1247
1248 The following environment variables are currently known to AnyEvent:
1174 1249
1175 "PERL_ANYEVENT_VERBOSE" 1250 "PERL_ANYEVENT_VERBOSE"
1176 By default, AnyEvent will be completely silent except in fatal 1251 By default, AnyEvent will log messages with loglevel 4 ("error") or
1177 conditions. You can set this environment variable to make AnyEvent 1252 higher (see AnyEvent::Log). You can set this environment variable to
1178 more talkative. 1253 a numerical loglevel to make AnyEvent more (or less) talkative.
1179 1254
1255 If you want to do more than just set the global logging level you
1256 should have a look at "PERL_ANYEVENT_LOG", which allows much more
1257 complex specifications.
1258
1259 When set to 0 ("off"), then no messages whatsoever will be logged
1260 with everything else at defaults.
1261
1180 When set to 5 or higher, causes AnyEvent to warn about unexpected 1262 When set to 5 or higher ("warn"), AnyEvent warns about unexpected
1181 conditions, such as not being able to load the event model specified 1263 conditions, such as not being able to load the event model specified
1182 by "PERL_ANYEVENT_MODEL". 1264 by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
1265 - this is the minimum recommended level for use during development.
1183 1266
1184 When set to 7 or higher, cause AnyEvent to report to STDERR which 1267 When set to 7 or higher (info), AnyEvent reports which event model
1185 event model it chooses. 1268 it chooses.
1186 1269
1187 When set to 8 or higher, then AnyEvent will report extra information 1270 When set to 8 or higher (debug), then AnyEvent will report extra
1188 on which optional modules it loads and how it implements certain 1271 information on which optional modules it loads and how it implements
1189 features. 1272 certain features.
1273
1274 "PERL_ANYEVENT_LOG"
1275 Accepts rather complex logging specifications. For example, you
1276 could log all "debug" messages of some module to stderr, warnings
1277 and above to stderr, and errors and above to syslog, with:
1278
1279 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
1280
1281 For the rather extensive details, see AnyEvent::Log.
1282
1283 This variable is evaluated when AnyEvent (or AnyEvent::Log) is
1284 loaded, so will take effect even before AnyEvent has initialised
1285 itself.
1286
1287 Note that specifying this environment variable causes the
1288 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
1289 does not, so only using the latter saves a few hundred kB of memory
1290 unless a module explicitly needs the extra features of
1291 AnyEvent::Log.
1190 1292
1191 "PERL_ANYEVENT_STRICT" 1293 "PERL_ANYEVENT_STRICT"
1192 AnyEvent does not do much argument checking by default, as thorough 1294 AnyEvent does not do much argument checking by default, as thorough
1193 argument checking is very costly. Setting this variable to a true 1295 argument checking is very costly. Setting this variable to a true
1194 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1296 value will cause AnyEvent to load "AnyEvent::Strict" and then to
… …
1201 is definitely recommended to keep it off in production. Keeping 1303 is definitely recommended to keep it off in production. Keeping
1202 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1304 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1203 programs can be very useful, however. 1305 programs can be very useful, however.
1204 1306
1205 "PERL_ANYEVENT_DEBUG_SHELL" 1307 "PERL_ANYEVENT_DEBUG_SHELL"
1206 If this env variable is set, then its contents will be interpreted 1308 If this env variable is nonempty, then its contents will be
1207 by "AnyEvent::Socket::parse_hostport" (after replacing every 1309 interpreted by "AnyEvent::Socket::parse_hostport" and
1208 occurance of $$ by the process pid) and an "AnyEvent::Debug::shell" 1310 "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
1209 is bound on that port. The shell object is saved in 1311 the process pid). The shell object is saved in
1210 $AnyEvent::Debug::SHELL. 1312 $AnyEvent::Debug::SHELL.
1211 1313
1212 This takes place when the first watcher is created. 1314 This happens when the first watcher is created.
1213 1315
1214 For example, to bind a debug shell on a unix domain socket in 1316 For example, to bind a debug shell on a unix domain socket in
1215 /tmp/debug<pid>.sock, you could use this: 1317 /tmp/debug<pid>.sock, you could use this:
1216 1318
1217 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 1319 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1320 # connect with e.g.: socat readline /tmp/debug123.sock
1218 1321
1322 Or to bind to tcp port 4545 on localhost:
1323
1324 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
1325 # connect with e.g.: telnet localhost 4545
1326
1219 Note that creating sockets in /tmp is very unsafe on multiuser 1327 Note that creating sockets in /tmp or on localhost is very unsafe on
1220 systems. 1328 multiuser systems.
1221 1329
1222 "PERL_ANYEVENT_DEBUG_WRAP" 1330 "PERL_ANYEVENT_DEBUG_WRAP"
1223 Can be set to 0, 1 or 2 and enables wrapping of all watchers for 1331 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1224 debugging purposes. See "AnyEvent::Debug::wrap" for details. 1332 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1225 1333
… …
1241 For example, to force the pure perl model (AnyEvent::Loop::Perl) you 1349 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1242 could start your program like this: 1350 could start your program like this:
1243 1351
1244 PERL_ANYEVENT_MODEL=Perl perl ... 1352 PERL_ANYEVENT_MODEL=Perl perl ...
1245 1353
1354 "PERL_ANYEVENT_IO_MODEL"
1355 The current file I/O model - see AnyEvent::IO for more info.
1356
1357 At the moment, only "Perl" (small, pure-perl, synchronous) and
1358 "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
1359 if AnyEvent::AIO can be loaded, otherwise it is "Perl".
1360
1246 "PERL_ANYEVENT_PROTOCOLS" 1361 "PERL_ANYEVENT_PROTOCOLS"
1247 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 1362 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1248 preferences for IPv4 or IPv6. The default is unspecified (and might 1363 preferences for IPv4 or IPv6. The default is unspecified (and might
1249 change, or be the result of auto probing). 1364 change, or be the result of auto probing).
1250 1365
… …
1253 mentioned will be used, and preference will be given to protocols 1368 mentioned will be used, and preference will be given to protocols
1254 mentioned earlier in the list. 1369 mentioned earlier in the list.
1255 1370
1256 This variable can effectively be used for denial-of-service attacks 1371 This variable can effectively be used for denial-of-service attacks
1257 against local programs (e.g. when setuid), although the impact is 1372 against local programs (e.g. when setuid), although the impact is
1258 likely small, as the program has to handle conenction and other 1373 likely small, as the program has to handle connection and other
1259 failures anyways. 1374 failures anyways.
1260 1375
1261 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 1376 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1262 IPv6, but support both and try to use both. 1377 IPv6, but support both and try to use both.
1263 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1378 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1264 resolve or contact IPv6 addresses. 1379 resolve or contact IPv6 addresses.
1265 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but 1380 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1266 prefer IPv6 over IPv4. 1381 prefer IPv6 over IPv4.
1267 1382
1383 "PERL_ANYEVENT_HOSTS"
1384 This variable, if specified, overrides the /etc/hosts file used by
1385 AnyEvent::Socket"::resolve_sockaddr", i.e. hosts aliases will be
1386 read from that file instead.
1387
1268 "PERL_ANYEVENT_EDNS0" 1388 "PERL_ANYEVENT_EDNS0"
1269 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension 1389 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1270 for DNS. This extension is generally useful to reduce DNS traffic, 1390 for DNS. This extension is generally useful to reduce DNS traffic,
1271 but some (broken) firewalls drop such DNS packets, which is why it 1391 especially when DNSSEC is involved, but some (broken) firewalls drop
1272 is off by default. 1392 such DNS packets, which is why it is off by default.
1273 1393
1274 Setting this variable to 1 will cause AnyEvent::DNS to announce 1394 Setting this variable to 1 will cause AnyEvent::DNS to announce
1275 EDNS0 in its DNS requests. 1395 EDNS0 in its DNS requests.
1276 1396
1277 "PERL_ANYEVENT_MAX_FORKS" 1397 "PERL_ANYEVENT_MAX_FORKS"
… …
1281 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" 1401 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1282 The default value for the "max_outstanding" parameter for the 1402 The default value for the "max_outstanding" parameter for the
1283 default DNS resolver - this is the maximum number of parallel DNS 1403 default DNS resolver - this is the maximum number of parallel DNS
1284 requests that are sent to the DNS server. 1404 requests that are sent to the DNS server.
1285 1405
1406 "PERL_ANYEVENT_MAX_SIGNAL_LATENCY"
1407 Perl has inherently racy signal handling (you can basically choose
1408 between losing signals and memory corruption) - pure perl event
1409 loops (including "AnyEvent::Loop", when "Async::Interrupt" isn't
1410 available) therefore have to poll regularly to avoid losing signals.
1411
1412 Some event loops are racy, but don't poll regularly, and some event
1413 loops are written in C but are still racy. For those event loops,
1414 AnyEvent installs a timer that regularly wakes up the event loop.
1415
1416 By default, the interval for this timer is 10 seconds, but you can
1417 override this delay with this environment variable (or by setting
1418 the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
1419 watchers).
1420
1421 Lower values increase CPU (and energy) usage, higher values can
1422 introduce long delays when reaping children or waiting for signals.
1423
1424 The AnyEvent::Async module, if available, will be used to avoid this
1425 polling (with most event loops).
1426
1286 "PERL_ANYEVENT_RESOLV_CONF" 1427 "PERL_ANYEVENT_RESOLV_CONF"
1287 The file to use instead of /etc/resolv.conf (or OS-specific 1428 The absolute path to a resolv.conf-style file to use instead of
1288 configuration) in the default resolver. When set to the empty 1429 /etc/resolv.conf (or the OS-specific configuration) in the default
1289 string, no default config will be used. 1430 resolver, or the empty string to select the default configuration.
1290 1431
1291 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". 1432 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1292 When neither "ca_file" nor "ca_path" was specified during 1433 When neither "ca_file" nor "ca_path" was specified during
1293 AnyEvent::TLS context creation, and either of these environment 1434 AnyEvent::TLS context creation, and either of these environment
1294 variables exist, they will be used to specify CA certificate 1435 variables are nonempty, they will be used to specify CA certificate
1295 locations instead of a system-dependent default. 1436 locations instead of a system-dependent default.
1296 1437
1297 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT" 1438 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1298 When these are set to 1, then the respective modules are not loaded. 1439 When these are set to 1, then the respective modules are not loaded.
1299 Mostly good for testing AnyEvent itself. 1440 Mostly good for testing AnyEvent itself.
… …
1471 my $txn = shift; 1612 my $txn = shift;
1472 my $data = $txn->result; 1613 my $data = $txn->result;
1473 ... 1614 ...
1474 }); 1615 });
1475 1616
1476 EV::loop; 1617 EV::run;
1477 1618
1478 3b. The module user could use AnyEvent, too: 1619 3b. The module user could use AnyEvent, too:
1479 1620
1480 use AnyEvent; 1621 use AnyEvent;
1481 1622
… …
1892 This module is part of perl since release 5.008. It will be used 2033 This module is part of perl since release 5.008. It will be used
1893 when the chosen event library does not come with a timing source of 2034 when the chosen event library does not come with a timing source of
1894 its own. The pure-perl event loop (AnyEvent::Loop) will additionally 2035 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
1895 load it to try to use a monotonic clock for timing stability. 2036 load it to try to use a monotonic clock for timing stability.
1896 2037
2038 AnyEvent::AIO (and IO::AIO)
2039 The default implementation of AnyEvent::IO is to do I/O
2040 synchronously, stopping programs while they access the disk, which
2041 is fine for a lot of programs.
2042
2043 Installing AnyEvent::AIO (and its IO::AIO dependency) makes it
2044 switch to a true asynchronous implementation, so event processing
2045 can continue even while waiting for disk I/O.
2046
1897FORK 2047FORK
1898 Most event libraries are not fork-safe. The ones who are usually are 2048 Most event libraries are not fork-safe. The ones who are usually are
1899 because they rely on inefficient but fork-safe "select" or "poll" calls 2049 because they rely on inefficient but fork-safe "select" or "poll" calls
1900 - higher performance APIs such as BSD's kqueue or the dreaded Linux 2050 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1901 epoll are usually badly thought-out hacks that are incompatible with 2051 epoll are usually badly thought-out hacks that are incompatible with
… …
1908 usually happens when the first AnyEvent watcher is created, or the 2058 usually happens when the first AnyEvent watcher is created, or the
1909 library is loaded). 2059 library is loaded).
1910 2060
1911 If you have to fork, you must either do so *before* creating your first 2061 If you have to fork, you must either do so *before* creating your first
1912 watcher OR you must not use AnyEvent at all in the child OR you must do 2062 watcher OR you must not use AnyEvent at all in the child OR you must do
1913 something completely out of the scope of AnyEvent. 2063 something completely out of the scope of AnyEvent (see below).
1914 2064
1915 The problem of doing event processing in the parent *and* the child is 2065 The problem of doing event processing in the parent *and* the child is
1916 much more complicated: even for backends that *are* fork-aware or 2066 much more complicated: even for backends that *are* fork-aware or
1917 fork-safe, their behaviour is not usually what you want: fork clones all 2067 fork-safe, their behaviour is not usually what you want: fork clones all
1918 watchers, that means all timers, I/O watchers etc. are active in both 2068 watchers, that means all timers, I/O watchers etc. are active in both
1919 parent and child, which is almost never what you want. USing "exec" to 2069 parent and child, which is almost never what you want. Using "exec" to
1920 start worker children from some kind of manage rprocess is usually 2070 start worker children from some kind of manage prrocess is usually
1921 preferred, because it is much easier and cleaner, at the expense of 2071 preferred, because it is much easier and cleaner, at the expense of
1922 having to have another binary. 2072 having to have another binary.
2073
2074 In addition to logical problems with fork, there are also implementation
2075 problems. For example, on POSIX systems, you cannot fork at all in Perl
2076 code if a thread (I am talking of pthreads here) was ever created in the
2077 process, and this is just the tip of the iceberg. In general, using fork
2078 from Perl is difficult, and attempting to use fork without an exec to
2079 implement some kind of parallel processing is almost certainly doomed.
2080
2081 To safely fork and exec, you should use a module such as Proc::FastSpawn
2082 that let's you safely fork and exec new processes.
2083
2084 If you want to do multiprocessing using processes, you can look at the
2085 AnyEvent::Fork module (and some related modules such as
2086 AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote).
2087 This module allows you to safely create subprocesses without any
2088 limitations - you can use X11 toolkits or AnyEvent in the children
2089 created by AnyEvent::Fork safely and without any special precautions.
1923 2090
1924SECURITY CONSIDERATIONS 2091SECURITY CONSIDERATIONS
1925 AnyEvent can be forced to load any event model via 2092 AnyEvent can be forced to load any event model via
1926 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 2093 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1927 to execute arbitrary code or directly gain access, it can easily be used 2094 to execute arbitrary code or directly gain access, it can easily be used
… …
1962 2129
1963 Development/Debugging: AnyEvent::Strict (stricter checking), 2130 Development/Debugging: AnyEvent::Strict (stricter checking),
1964 AnyEvent::Debug (interactive shell, watcher tracing). 2131 AnyEvent::Debug (interactive shell, watcher tracing).
1965 2132
1966 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, 2133 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
1967 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK. 2134 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV.
1968 2135
1969 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 2136 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1970 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 2137 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1971 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 2138 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1972 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.
1973 2141
1974 Non-blocking handles, pipes, stream sockets, TCP clients and servers: 2142 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
1975 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 2143 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1976 2144
2145 Asynchronous File I/O: AnyEvent::IO.
2146
1977 Asynchronous DNS: AnyEvent::DNS. 2147 Asynchronous DNS: AnyEvent::DNS.
1978 2148
1979 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event. 2149 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1980 2150
1981 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC, 2151 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1982 AnyEvent::HTTP. 2152 AnyEvent::HTTP.
1983 2153
1984AUTHOR 2154AUTHOR
1985 Marc Lehmann <schmorp@schmorp.de> 2155 Marc Lehmann <schmorp@schmorp.de>
1986 http://home.schmorp.de/ 2156 http://anyevent.schmorp.de
1987 2157

Diff Legend

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