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

Comparing cvsroot/AnyEvent/README (file contents):
Revision 1.66 by root, Sun Aug 21 03:02:32 2011 UTC vs.
Revision 1.73 by root, Fri Sep 5 22:24:12 2014 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
… …
834 by the main program. 844 by the main program.
835 845
836 AnyEvent::Impl::Event based on Event, very stable, few glitches. 846 AnyEvent::Impl::Event based on Event, very stable, few glitches.
837 AnyEvent::Impl::Glib based on Glib, slow but very stable. 847 AnyEvent::Impl::Glib based on Glib, slow but very stable.
838 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.
839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 850 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
840 AnyEvent::Impl::POE based on POE, very slow, some limitations. 851 AnyEvent::Impl::POE based on POE, very slow, some limitations.
841 AnyEvent::Impl::Irssi used when running within irssi. 852 AnyEvent::Impl::Irssi used when running within irssi.
842 AnyEvent::Impl::IOAsync based on IO::Async. 853 AnyEvent::Impl::IOAsync based on IO::Async.
843 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 854 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
844 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 855 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
845 856
846 Backends with special needs. 857 Backends with special needs.
847 Qt requires the Qt::Application to be instantiated first, but will 858 Qt requires the Qt::Application to be instantiated first, but will
848 otherwise be picked up automatically. As long as the main program 859 otherwise be picked up automatically. As long as the main program
849 instantiates the application before any AnyEvent watchers are 860 instantiates the application before any AnyEvent watchers are
… …
975 To understand the usefulness of this function, consider a function 986 To understand the usefulness of this function, consider a function
976 that asynchronously does something for you and returns some 987 that asynchronously does something for you and returns some
977 transaction object or guard to let you cancel the operation. For 988 transaction object or guard to let you cancel the operation. For
978 example, "AnyEvent::Socket::tcp_connect": 989 example, "AnyEvent::Socket::tcp_connect":
979 990
980 # start a conenction attempt unless one is active 991 # start a connection attempt unless one is active
981 $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 {
982 delete $self->{connect_guard}; 993 delete $self->{connect_guard};
983 ... 994 ...
984 }; 995 };
985 996
… …
1005 if $some_error_condition; 1016 if $some_error_condition;
1006 1017
1007 AnyEvent::log $level, $msg[, @args] 1018 AnyEvent::log $level, $msg[, @args]
1008 Log the given $msg at the given $level. 1019 Log the given $msg at the given $level.
1009 1020
1021 If AnyEvent::Log is not loaded then this function makes a simple
1022 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" - 1023 it will load AnyEvent::Log and call "AnyEvent::Log::log" -
1011 consequently, look at the AnyEvent::Log documentation for details. 1024 consequently, look at the AnyEvent::Log documentation for details.
1025
1026 If the test fails it will simply return. Right now this happens when
1027 a numerical loglevel is used and it is larger than the level
1028 specified via $ENV{PERL_ANYEVENT_VERBOSE}.
1012 1029
1013 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,
1014 consider creating a logger callback with the "AnyEvent::Log::logger" 1031 consider creating a logger callback with the "AnyEvent::Log::logger"
1015 function. 1032 function, which can reduce typing, codesize and can reduce the
1033 logging overhead enourmously.
1016 1034
1017WHAT TO DO IN A MODULE 1035WHAT TO DO IN A MODULE
1018 As a module author, you should "use AnyEvent" and call AnyEvent methods 1036 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. 1037 freely, but you should not load a specific event module or rely on it.
1020 1038
… …
1079 modules come as part of AnyEvent, the others are available via CPAN (see 1097 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 1098 <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 1099 non-exhaustive list), and the list is heavily biased towards modules of
1082 the AnyEvent author himself :) 1100 the AnyEvent author himself :)
1083 1101
1084 AnyEvent::Util 1102 AnyEvent::Util (part of the AnyEvent distribution)
1085 Contains various utility functions that replace often-used blocking 1103 Contains various utility functions that replace often-used blocking
1086 functions such as "inet_aton" with event/callback-based versions. 1104 functions such as "inet_aton" with event/callback-based versions.
1087 1105
1088 AnyEvent::Socket 1106 AnyEvent::Socket (part of the AnyEvent distribution)
1089 Provides various utility functions for (internet protocol) sockets, 1107 Provides various utility functions for (internet protocol) sockets,
1090 addresses and name resolution. Also functions to create non-blocking 1108 addresses and name resolution. Also functions to create non-blocking
1091 tcp connections or tcp servers, with IPv6 and SRV record support and 1109 tcp connections or tcp servers, with IPv6 and SRV record support and
1092 more. 1110 more.
1093 1111
1094 AnyEvent::Handle 1112 AnyEvent::Handle (part of the AnyEvent distribution)
1095 Provide read and write buffers, manages watchers for reads and 1113 Provide read and write buffers, manages watchers for reads and
1096 writes, supports raw and formatted I/O, I/O queued and fully 1114 writes, supports raw and formatted I/O, I/O queued and fully
1097 transparent and non-blocking SSL/TLS (via AnyEvent::TLS). 1115 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1098 1116
1099 AnyEvent::DNS 1117 AnyEvent::DNS (part of the AnyEvent distribution)
1100 Provides rich asynchronous DNS resolver capabilities. 1118 Provides rich asynchronous DNS resolver capabilities.
1101 1119
1102 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1120 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1103 AnyEvent::IGS, AnyEvent::FCP 1121 AnyEvent::IGS, AnyEvent::FCP
1104 Implement event-based interfaces to the protocols of the same name 1122 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 1123 (for the curious, IGS is the International Go Server and FCP is the
1106 Freenet Client Protocol). 1124 Freenet Client Protocol).
1107 1125
1108 AnyEvent::Handle::UDP 1126 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 1127 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1131 the toolbox of every event programmer. AnyEvent::AIO transparently 1128 the toolbox of every event programmer. AnyEvent::AIO transparently
1132 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1129 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1133 event-based file I/O, and much more. 1130 event-based file I/O, and much more.
1134 1131
1132 AnyEvent::Fork, AnyEvent::Fork::RPC, AnyEvent::Fork::Pool,
1133 AnyEvent::Fork::Remote
1134 These let you safely fork new subprocesses, either locally or
1135 remotely (e.g.v ia ssh), using some RPC protocol or not, without the
1136 limitations normally imposed by fork (AnyEvent works fine for
1137 example). Dynamically-resized worker pools are obviously included as
1138 well.
1139
1140 And they are quite tiny and fast as well - "abusing" AnyEvent::Fork
1141 just to exec external programs can easily beat using "fork" and
1142 "exec" (or even "system") in most programs.
1143
1144 AnyEvent::Filesys::Notify
1145 AnyEvent is good for non-blocking stuff, but it can't detect file or
1146 path changes (e.g. "watch this directory for new files", "watch this
1147 file for changes"). The AnyEvent::Filesys::Notify module promises to
1148 do just that in a portbale fashion, supporting inotify on GNU/Linux
1149 and some weird, without doubt broken, stuff on OS X to monitor
1150 files. It can fall back to blocking scans at regular intervals
1151 transparently on other platforms, so it's about as portable as it
1152 gets.
1153
1154 (I haven't used it myself, but it seems the biggest problem with it
1155 is it quite bad performance).
1156
1135 AnyEvent::HTTPD 1157 AnyEvent::DBI
1136 A simple embedded webserver. 1158 Executes DBI requests asynchronously in a proxy process for you,
1159 notifying you in an event-based way when the operation is finished.
1137 1160
1138 AnyEvent::FastPing 1161 AnyEvent::FastPing
1139 The fastest ping in the west. 1162 The fastest ping in the west.
1140 1163
1141 Coro 1164 Coro
1142 Has special support for AnyEvent via Coro::AnyEvent. 1165 Has special support for AnyEvent via Coro::AnyEvent, which allows
1166 you to simply invert the flow control - don't call us, we will call
1167 you:
1168
1169 async {
1170 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1171 print "5 seconds later!\n";
1172
1173 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1174 my $line = <STDIN>; # works for ttys
1175
1176 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1177 my ($body, $hdr) = Coro::rouse_wait;
1178 };
1143 1179
1144SIMPLIFIED AE API 1180SIMPLIFIED AE API
1145 Starting with version 5.0, AnyEvent officially supports a second, much 1181 Starting with version 5.0, AnyEvent officially supports a second, much
1146 simpler, API that is designed to reduce the calling, typing and memory 1182 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. 1183 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 1199 The pure perl event loop simply re-throws the exception (usually within
1164 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 1200 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1165 Glib uses "install_exception_handler" and so on. 1201 Glib uses "install_exception_handler" and so on.
1166 1202
1167ENVIRONMENT VARIABLES 1203ENVIRONMENT VARIABLES
1168 The following environment variables are used by this module or its 1204 AnyEvent supports a number of environment variables that tune the
1169 submodules. 1205 runtime behaviour. They are usually evaluated when AnyEvent is loaded,
1206 initialised, or a submodule that uses them is loaded. Many of them also
1207 cause AnyEvent to load additional modules - for example,
1208 "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be
1209 loaded.
1170 1210
1171 Note that AnyEvent will remove *all* environment variables starting with 1211 All the environment variables documented here start with
1172 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is 1212 "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace.
1173 enabled. 1213 Other modules are encouraged (but by no means required) to use
1214 "PERL_ANYEVENT_SUBMODULE" if they have registered the
1215 AnyEvent::Submodule namespace on CPAN, for any submodule. For example,
1216 AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it
1217 should not access env variables starting with "AE_", see below).
1218
1219 All variables can also be set via the "AE_" prefix, that is, instead of
1220 setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case
1221 there is a clash btween anyevent and another program that uses
1222 "AE_something" you can set the corresponding "PERL_ANYEVENT_something"
1223 variable to the empty string, as those variables take precedence.
1224
1225 When AnyEvent is first loaded, it copies all "AE_xxx" env variables to
1226 their "PERL_ANYEVENT_xxx" counterpart unless that variable already
1227 exists. If taint mode is on, then AnyEvent will remove *all* environment
1228 variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with
1229 "undef" or the empty string, if the corresaponding "AE_" variable is
1230 set).
1231
1232 The exact algorithm is currently:
1233
1234 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
1235 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
1236 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
1237
1238 This ensures that child processes will not see the "AE_" variables.
1239
1240 The following environment variables are currently known to AnyEvent:
1174 1241
1175 "PERL_ANYEVENT_VERBOSE" 1242 "PERL_ANYEVENT_VERBOSE"
1176 By default, AnyEvent will be completely silent except in fatal 1243 By default, AnyEvent will log messages with loglevel 4 ("error") or
1177 conditions. You can set this environment variable to make AnyEvent 1244 higher (see AnyEvent::Log). You can set this environment variable to
1178 more talkative. 1245 a numerical loglevel to make AnyEvent more (or less) talkative.
1179 1246
1247 If you want to do more than just set the global logging level you
1248 should have a look at "PERL_ANYEVENT_LOG", which allows much more
1249 complex specifications.
1250
1251 When set to 0 ("off"), then no messages whatsoever will be logged
1252 with everything else at defaults.
1253
1180 When set to 5 or higher, causes AnyEvent to warn about unexpected 1254 When set to 5 or higher ("warn"), AnyEvent warns about unexpected
1181 conditions, such as not being able to load the event model specified 1255 conditions, such as not being able to load the event model specified
1182 by "PERL_ANYEVENT_MODEL". 1256 by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
1257 - this is the minimum recommended level for use during development.
1183 1258
1184 When set to 7 or higher, cause AnyEvent to report to STDERR which 1259 When set to 7 or higher (info), AnyEvent reports which event model
1185 event model it chooses. 1260 it chooses.
1186 1261
1187 When set to 8 or higher, then AnyEvent will report extra information 1262 When set to 8 or higher (debug), then AnyEvent will report extra
1188 on which optional modules it loads and how it implements certain 1263 information on which optional modules it loads and how it implements
1189 features. 1264 certain features.
1265
1266 "PERL_ANYEVENT_LOG"
1267 Accepts rather complex logging specifications. For example, you
1268 could log all "debug" messages of some module to stderr, warnings
1269 and above to stderr, and errors and above to syslog, with:
1270
1271 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
1272
1273 For the rather extensive details, see AnyEvent::Log.
1274
1275 This variable is evaluated when AnyEvent (or AnyEvent::Log) is
1276 loaded, so will take effect even before AnyEvent has initialised
1277 itself.
1278
1279 Note that specifying this environment variable causes the
1280 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
1281 does not, so only using the latter saves a few hundred kB of memory
1282 unless a module explicitly needs the extra features of
1283 AnyEvent::Log.
1190 1284
1191 "PERL_ANYEVENT_STRICT" 1285 "PERL_ANYEVENT_STRICT"
1192 AnyEvent does not do much argument checking by default, as thorough 1286 AnyEvent does not do much argument checking by default, as thorough
1193 argument checking is very costly. Setting this variable to a true 1287 argument checking is very costly. Setting this variable to a true
1194 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1288 value will cause AnyEvent to load "AnyEvent::Strict" and then to
… …
1201 is definitely recommended to keep it off in production. Keeping 1295 is definitely recommended to keep it off in production. Keeping
1202 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1296 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1203 programs can be very useful, however. 1297 programs can be very useful, however.
1204 1298
1205 "PERL_ANYEVENT_DEBUG_SHELL" 1299 "PERL_ANYEVENT_DEBUG_SHELL"
1206 If this env variable is set, then its contents will be interpreted 1300 If this env variable is nonempty, then its contents will be
1207 by "AnyEvent::Socket::parse_hostport" (after replacing every 1301 interpreted by "AnyEvent::Socket::parse_hostport" and
1208 occurance of $$ by the process pid) and an "AnyEvent::Debug::shell" 1302 "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
1209 is bound on that port. The shell object is saved in 1303 the process pid). The shell object is saved in
1210 $AnyEvent::Debug::SHELL. 1304 $AnyEvent::Debug::SHELL.
1211 1305
1212 This takes place when the first watcher is created. 1306 This happens when the first watcher is created.
1213 1307
1214 For example, to bind a debug shell on a unix domain socket in 1308 For example, to bind a debug shell on a unix domain socket in
1215 /tmp/debug<pid>.sock, you could use this: 1309 /tmp/debug<pid>.sock, you could use this:
1216 1310
1217 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 1311 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1312 # connect with e.g.: socat readline /tmp/debug123.sock
1218 1313
1314 Or to bind to tcp port 4545 on localhost:
1315
1316 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
1317 # connect with e.g.: telnet localhost 4545
1318
1219 Note that creating sockets in /tmp is very unsafe on multiuser 1319 Note that creating sockets in /tmp or on localhost is very unsafe on
1220 systems. 1320 multiuser systems.
1221 1321
1222 "PERL_ANYEVENT_DEBUG_WRAP" 1322 "PERL_ANYEVENT_DEBUG_WRAP"
1223 Can be set to 0, 1 or 2 and enables wrapping of all watchers for 1323 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1224 debugging purposes. See "AnyEvent::Debug::wrap" for details. 1324 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1225 1325
… …
1241 For example, to force the pure perl model (AnyEvent::Loop::Perl) you 1341 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1242 could start your program like this: 1342 could start your program like this:
1243 1343
1244 PERL_ANYEVENT_MODEL=Perl perl ... 1344 PERL_ANYEVENT_MODEL=Perl perl ...
1245 1345
1346 "PERL_ANYEVENT_IO_MODEL"
1347 The current file I/O model - see AnyEvent::IO for more info.
1348
1349 At the moment, only "Perl" (small, pure-perl, synchronous) and
1350 "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
1351 if AnyEvent::AIO can be loaded, otherwise it is "Perl".
1352
1246 "PERL_ANYEVENT_PROTOCOLS" 1353 "PERL_ANYEVENT_PROTOCOLS"
1247 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 1354 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1248 preferences for IPv4 or IPv6. The default is unspecified (and might 1355 preferences for IPv4 or IPv6. The default is unspecified (and might
1249 change, or be the result of auto probing). 1356 change, or be the result of auto probing).
1250 1357
… …
1253 mentioned will be used, and preference will be given to protocols 1360 mentioned will be used, and preference will be given to protocols
1254 mentioned earlier in the list. 1361 mentioned earlier in the list.
1255 1362
1256 This variable can effectively be used for denial-of-service attacks 1363 This variable can effectively be used for denial-of-service attacks
1257 against local programs (e.g. when setuid), although the impact is 1364 against local programs (e.g. when setuid), although the impact is
1258 likely small, as the program has to handle conenction and other 1365 likely small, as the program has to handle connection and other
1259 failures anyways. 1366 failures anyways.
1260 1367
1261 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 1368 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1262 IPv6, but support both and try to use both. 1369 IPv6, but support both and try to use both.
1263 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1370 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1264 resolve or contact IPv6 addresses. 1371 resolve or contact IPv6 addresses.
1265 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but 1372 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1266 prefer IPv6 over IPv4. 1373 prefer IPv6 over IPv4.
1267 1374
1375 "PERL_ANYEVENT_HOSTS"
1376 This variable, if specified, overrides the /etc/hosts file used by
1377 AnyEvent::Socket"::resolve_sockaddr", i.e. hosts aliases will be
1378 read from that file instead.
1379
1268 "PERL_ANYEVENT_EDNS0" 1380 "PERL_ANYEVENT_EDNS0"
1269 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension 1381 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1270 for DNS. This extension is generally useful to reduce DNS traffic, 1382 for DNS. This extension is generally useful to reduce DNS traffic,
1271 but some (broken) firewalls drop such DNS packets, which is why it 1383 especially when DNSSEC is involved, but some (broken) firewalls drop
1272 is off by default. 1384 such DNS packets, which is why it is off by default.
1273 1385
1274 Setting this variable to 1 will cause AnyEvent::DNS to announce 1386 Setting this variable to 1 will cause AnyEvent::DNS to announce
1275 EDNS0 in its DNS requests. 1387 EDNS0 in its DNS requests.
1276 1388
1277 "PERL_ANYEVENT_MAX_FORKS" 1389 "PERL_ANYEVENT_MAX_FORKS"
… …
1281 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" 1393 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1282 The default value for the "max_outstanding" parameter for the 1394 The default value for the "max_outstanding" parameter for the
1283 default DNS resolver - this is the maximum number of parallel DNS 1395 default DNS resolver - this is the maximum number of parallel DNS
1284 requests that are sent to the DNS server. 1396 requests that are sent to the DNS server.
1285 1397
1398 "PERL_ANYEVENT_MAX_SIGNAL_LATENCY"
1399 Perl has inherently racy signal handling (you can basically choose
1400 between losing signals and memory corruption) - pure perl event
1401 loops (including "AnyEvent::Loop", when "Async::Interrupt" isn't
1402 available) therefore have to poll regularly to avoid losing signals.
1403
1404 Some event loops are racy, but don't poll regularly, and some event
1405 loops are written in C but are still racy. For those event loops,
1406 AnyEvent installs a timer that regularly wakes up the event loop.
1407
1408 By default, the interval for this timer is 10 seconds, but you can
1409 override this delay with this environment variable (or by setting
1410 the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
1411 watchers).
1412
1413 Lower values increase CPU (and energy) usage, higher values can
1414 introduce long delays when reaping children or waiting for signals.
1415
1416 The AnyEvent::Async module, if available, will be used to avoid this
1417 polling (with most event loops).
1418
1286 "PERL_ANYEVENT_RESOLV_CONF" 1419 "PERL_ANYEVENT_RESOLV_CONF"
1287 The file to use instead of /etc/resolv.conf (or OS-specific 1420 The absolute path to a resolv.conf-style file to use instead of
1288 configuration) in the default resolver. When set to the empty 1421 /etc/resolv.conf (or the OS-specific configuration) in the default
1289 string, no default config will be used. 1422 resolver, or the empty string to select the default configuration.
1290 1423
1291 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". 1424 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1292 When neither "ca_file" nor "ca_path" was specified during 1425 When neither "ca_file" nor "ca_path" was specified during
1293 AnyEvent::TLS context creation, and either of these environment 1426 AnyEvent::TLS context creation, and either of these environment
1294 variables exist, they will be used to specify CA certificate 1427 variables are nonempty, they will be used to specify CA certificate
1295 locations instead of a system-dependent default. 1428 locations instead of a system-dependent default.
1296 1429
1297 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT" 1430 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1298 When these are set to 1, then the respective modules are not loaded. 1431 When these are set to 1, then the respective modules are not loaded.
1299 Mostly good for testing AnyEvent itself. 1432 Mostly good for testing AnyEvent itself.
… …
1892 This module is part of perl since release 5.008. It will be used 2025 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 2026 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 2027 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
1895 load it to try to use a monotonic clock for timing stability. 2028 load it to try to use a monotonic clock for timing stability.
1896 2029
2030 AnyEvent::AIO (and IO::AIO)
2031 The default implementation of AnyEvent::IO is to do I/O
2032 synchronously, stopping programs while they access the disk, which
2033 is fine for a lot of programs.
2034
2035 Installing AnyEvent::AIO (and its IO::AIO dependency) makes it
2036 switch to a true asynchronous implementation, so event processing
2037 can continue even while waiting for disk I/O.
2038
1897FORK 2039FORK
1898 Most event libraries are not fork-safe. The ones who are usually are 2040 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 2041 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 2042 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1901 epoll are usually badly thought-out hacks that are incompatible with 2043 epoll are usually badly thought-out hacks that are incompatible with
… …
1908 usually happens when the first AnyEvent watcher is created, or the 2050 usually happens when the first AnyEvent watcher is created, or the
1909 library is loaded). 2051 library is loaded).
1910 2052
1911 If you have to fork, you must either do so *before* creating your first 2053 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 2054 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. 2055 something completely out of the scope of AnyEvent (see below).
1914 2056
1915 The problem of doing event processing in the parent *and* the child is 2057 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 2058 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 2059 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 2060 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 2061 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 2062 start worker children from some kind of manage prrocess is usually
1921 preferred, because it is much easier and cleaner, at the expense of 2063 preferred, because it is much easier and cleaner, at the expense of
1922 having to have another binary. 2064 having to have another binary.
2065
2066 In addition to logical problems with fork, there are also implementation
2067 problems. For example, on POSIX systems, you cannot fork at all in Perl
2068 code if a thread (I am talking of pthreads here) was ever created in the
2069 process, and this is just the tip of the iceberg. In general, using fork
2070 from Perl is difficult, and attempting to use fork without an exec to
2071 implement some kind of parallel processing is almost certainly doomed.
2072
2073 To safely fork and exec, you should use a module such as Proc::FastSpawn
2074 that let's you safely fork and exec new processes.
2075
2076 If you want to do multiprocessing using processes, you can look at the
2077 AnyEvent::Fork module (and some related modules such as
2078 AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote).
2079 This module allows you to safely create subprocesses without any
2080 limitations - you can use X11 toolkits or AnyEvent in the children
2081 created by AnyEvent::Fork safely and without any special precautions.
1923 2082
1924SECURITY CONSIDERATIONS 2083SECURITY CONSIDERATIONS
1925 AnyEvent can be forced to load any event model via 2084 AnyEvent can be forced to load any event model via
1926 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 2085 $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 2086 to execute arbitrary code or directly gain access, it can easily be used
… …
1972 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK. 2131 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK.
1973 2132
1974 Non-blocking handles, pipes, stream sockets, TCP clients and servers: 2133 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
1975 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 2134 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1976 2135
2136 Asynchronous File I/O: AnyEvent::IO.
2137
1977 Asynchronous DNS: AnyEvent::DNS. 2138 Asynchronous DNS: AnyEvent::DNS.
1978 2139
1979 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event. 2140 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1980 2141
1981 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC, 2142 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1982 AnyEvent::HTTP. 2143 AnyEvent::HTTP.
1983 2144
1984AUTHOR 2145AUTHOR
1985 Marc Lehmann <schmorp@schmorp.de> 2146 Marc Lehmann <schmorp@schmorp.de>
1986 http://home.schmorp.de/ 2147 http://anyevent.schmorp.de
1987 2148

Diff Legend

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