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

Comparing AnyEvent/README (file contents):
Revision 1.65 by root, Sat Aug 13 22:44:05 2011 UTC vs.
Revision 1.71 by root, Wed Aug 21 08:40:28 2013 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, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 Qt and POE are various supported event loops/environments. 5 Qt, FLTK and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # if you prefer function calls, look at the AE manpage for 10 # if you prefer function calls, look at the AE manpage for
262 262
263 Example 2: fire an event after 0.5 seconds, then roughly every second. 263 Example 2: fire an event after 0.5 seconds, then roughly every second.
264 264
265 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { 265 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
266 warn "timeout\n"; 266 warn "timeout\n";
267 }; 267 });
268 268
269 TIMING ISSUES 269 TIMING ISSUES
270 There are two ways to handle timers: based on real time (relative, "fire 270 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 271 in 10 seconds") and based on wallclock time (absolute, "fire at 12
272 o'clock"). 272 o'clock").
403 will not restart syscalls (that includes Async::Interrupt and AnyEvent's 403 will not restart syscalls (that includes Async::Interrupt and AnyEvent's
404 pure perl implementation). 404 pure perl implementation).
405 405
406 Safe/Unsafe Signals 406 Safe/Unsafe Signals
407 Perl signals can be either "safe" (synchronous to opcode handling) or 407 Perl signals can be either "safe" (synchronous to opcode handling) or
408 "unsafe" (asynchronous) - the former might get delayed indefinitely, the 408 "unsafe" (asynchronous) - the former might delay signal delivery
409 latter might corrupt your memory. 409 indefinitely, the latter might corrupt your memory.
410 410
411 AnyEvent signal handlers are, in addition, synchronous to the event 411 AnyEvent signal handlers are, in addition, synchronous to the event
412 loop, i.e. they will not interrupt your running perl program but will 412 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, 413 only be called as part of the normal event handling (just like timer,
414 I/O etc. callbacks, too). 414 I/O etc. callbacks, too).
416 Signal Races, Delays and Workarounds 416 Signal Races, Delays and Workarounds
417 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 417 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 418 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. 419 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 420 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 421 will be delayed. The maximum time a signal might be delayed is 10
422 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable 422 seconds by default, but can be overriden via
423 can be changed only before the first signal watcher is created, and 423 $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} or $AnyEvent::MAX_SIGNAL_LATENCY
424 should be left alone otherwise. This variable determines how often 424 - 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 425
429 All these problems can be avoided by installing the optional 426 All these problems can be avoided by installing the optional
430 Async::Interrupt module, which works with most event loops. It will not 427 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 428 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. 429 not with POE currently). For those, you just have to suffer the delays.
434 430
435 CHILD PROCESS WATCHERS 431 CHILD PROCESS WATCHERS
436 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 432 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
437 433
438 You can also watch for a child process exit and catch its exit status. 434 You can also watch for a child process exit and catch its exit status.
740 }; 736 };
741 } 737 }
742 738
743 $cv->end; 739 $cv->end;
744 740
741 ...
742
743 my $results = $cv->recv;
744
745 This code fragment supposedly pings a number of hosts and calls 745 This code fragment supposedly pings a number of hosts and calls
746 "send" after results for all then have have been gathered - in any 746 "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 747 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 748 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 749 result for it. Since "begin" and "end" only maintain a counter, the
778 In list context, all parameters passed to "send" will be returned, 778 In list context, all parameters passed to "send" will be returned,
779 in scalar context only the first one will be returned. 779 in scalar context only the first one will be returned.
780 780
781 Note that doing a blocking wait in a callback is not supported by 781 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" 782 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 783 is not allowed and the "recv" call will "croak" if such a condition
784 is detected. This condition can be slightly loosened by using 784 is detected. This requirement can be dropped by relying on
785 Coro::AnyEvent, which allows you to do a blocking "->recv" from any 785 Coro::AnyEvent , which allows you to do a blocking "->recv" from any
786 thread that doesn't run the event loop itself. 786 thread that doesn't run the event loop itself. Coro::AnyEvent is
787 loaded automatically when Coro is used with AnyEvent, so code does
788 not need to do anything special to take advantage of that: any code
789 that would normally block your program because it calls "recv", be
790 executed in an "async" thread instead without blocking other
791 threads.
787 792
788 Not all event models support a blocking wait - some die in that case 793 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 794 (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, 795 using this from a module, never require a blocking wait*. Instead,
791 let the caller decide whether the call will block or not (for 796 let the caller decide whether the call will block or not (for
839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 844 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
840 AnyEvent::Impl::POE based on POE, very slow, some limitations. 845 AnyEvent::Impl::POE based on POE, very slow, some limitations.
841 AnyEvent::Impl::Irssi used when running within irssi. 846 AnyEvent::Impl::Irssi used when running within irssi.
842 AnyEvent::Impl::IOAsync based on IO::Async. 847 AnyEvent::Impl::IOAsync based on IO::Async.
843 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 848 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
844 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 849 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
845 850
846 Backends with special needs. 851 Backends with special needs.
847 Qt requires the Qt::Application to be instantiated first, but will 852 Qt requires the Qt::Application to be instantiated first, but will
848 otherwise be picked up automatically. As long as the main program 853 otherwise be picked up automatically. As long as the main program
849 instantiates the application before any AnyEvent watchers are 854 instantiates the application before any AnyEvent watchers are
1002 It should use "postpone": 1007 It should use "postpone":
1003 1008
1004 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later 1009 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1005 if $some_error_condition; 1010 if $some_error_condition;
1006 1011
1012 AnyEvent::log $level, $msg[, @args]
1013 Log the given $msg at the given $level.
1014
1015 If AnyEvent::Log is not loaded then this function makes a simple
1016 test to see whether the message will be logged. If the test succeeds
1017 it will load AnyEvent::Log and call "AnyEvent::Log::log" -
1018 consequently, look at the AnyEvent::Log documentation for details.
1019
1020 If the test fails it will simply return. Right now this happens when
1021 a numerical loglevel is used and it is larger than the level
1022 specified via $ENV{PERL_ANYEVENT_VERBOSE}.
1023
1024 If you want to sprinkle loads of logging calls around your code,
1025 consider creating a logger callback with the "AnyEvent::Log::logger"
1026 function, which can reduce typing, codesize and can reduce the
1027 logging overhead enourmously.
1028
1007WHAT TO DO IN A MODULE 1029WHAT TO DO IN A MODULE
1008 As a module author, you should "use AnyEvent" and call AnyEvent methods 1030 As a module author, you should "use AnyEvent" and call AnyEvent methods
1009 freely, but you should not load a specific event module or rely on it. 1031 freely, but you should not load a specific event module or rely on it.
1010 1032
1011 Be careful when you create watchers in the module body - AnyEvent will 1033 Be careful when you create watchers in the module body - AnyEvent will
1064 1086
1065OTHER MODULES 1087OTHER MODULES
1066 The following is a non-exhaustive list of additional modules that use 1088 The following is a non-exhaustive list of additional modules that use
1067 AnyEvent as a client and can therefore be mixed easily with other 1089 AnyEvent as a client and can therefore be mixed easily with other
1068 AnyEvent modules and other event loops in the same program. Some of the 1090 AnyEvent modules and other event loops in the same program. Some of the
1069 modules come as part of AnyEvent, the others are available via CPAN. 1091 modules come as part of AnyEvent, the others are available via CPAN (see
1092 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer
1093 non-exhaustive list), and the list is heavily biased towards modules of
1094 the AnyEvent author himself :)
1070 1095
1071 AnyEvent::Util 1096 AnyEvent::Util (part of the AnyEvent distribution)
1072 Contains various utility functions that replace often-used blocking 1097 Contains various utility functions that replace often-used blocking
1073 functions such as "inet_aton" with event/callback-based versions. 1098 functions such as "inet_aton" with event/callback-based versions.
1074 1099
1075 AnyEvent::Socket 1100 AnyEvent::Socket (part of the AnyEvent distribution)
1076 Provides various utility functions for (internet protocol) sockets, 1101 Provides various utility functions for (internet protocol) sockets,
1077 addresses and name resolution. Also functions to create non-blocking 1102 addresses and name resolution. Also functions to create non-blocking
1078 tcp connections or tcp servers, with IPv6 and SRV record support and 1103 tcp connections or tcp servers, with IPv6 and SRV record support and
1079 more. 1104 more.
1080 1105
1081 AnyEvent::Handle 1106 AnyEvent::Handle (part of the AnyEvent distribution)
1082 Provide read and write buffers, manages watchers for reads and 1107 Provide read and write buffers, manages watchers for reads and
1083 writes, supports raw and formatted I/O, I/O queued and fully 1108 writes, supports raw and formatted I/O, I/O queued and fully
1084 transparent and non-blocking SSL/TLS (via AnyEvent::TLS). 1109 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1085 1110
1086 AnyEvent::DNS 1111 AnyEvent::DNS (part of the AnyEvent distribution)
1087 Provides rich asynchronous DNS resolver capabilities. 1112 Provides rich asynchronous DNS resolver capabilities.
1088 1113
1089 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1114 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1090 AnyEvent::IGS, AnyEvent::FCP 1115 AnyEvent::IGS, AnyEvent::FCP
1091 Implement event-based interfaces to the protocols of the same name 1116 Implement event-based interfaces to the protocols of the same name
1092 (for the curious, IGS is the International Go Server and FCP is the 1117 (for the curious, IGS is the International Go Server and FCP is the
1093 Freenet Client Protocol). 1118 Freenet Client Protocol).
1094 1119
1095 AnyEvent::Handle::UDP 1120 AnyEvent::AIO (part of the AnyEvent distribution)
1096 Here be danger!
1097
1098 As Pauli would put it, "Not only is it not right, it's not even
1099 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
1100 most notably its use of a stream-based API with a protocol that
1101 isn't streamable, that the only way to improve it is to delete it.
1102
1103 It features data corruption (but typically only under load) and
1104 general confusion. On top, the author is not only clueless about UDP
1105 but also fact-resistant - some gems of his understanding: "connect
1106 doesn't work with UDP", "UDP packets are not IP packets", "UDP only
1107 has datagrams, not packets", "I don't need to implement proper error
1108 checking as UDP doesn't support error checking" and so on - he
1109 doesn't even understand what's wrong with his module when it is
1110 explained to him.
1111
1112 AnyEvent::DBI
1113 Executes DBI requests asynchronously in a proxy process for you,
1114 notifying you in an event-based way when the operation is finished.
1115
1116 AnyEvent::AIO
1117 Truly asynchronous (as opposed to non-blocking) I/O, should be in 1121 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1118 the toolbox of every event programmer. AnyEvent::AIO transparently 1122 the toolbox of every event programmer. AnyEvent::AIO transparently
1119 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1123 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1120 event-based file I/O, and much more. 1124 event-based file I/O, and much more.
1121 1125
1126 AnyEvent::Filesys::Notify
1127 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
1129 file for changes"). The AnyEvent::Filesys::Notify module promises to
1130 do just that in a portbale fashion, supporting inotify on GNU/Linux
1131 and some weird, without doubt broken, stuff on OS X to monitor
1132 files. It can fall back to blocking scans at regular intervals
1133 transparently on other platforms, so it's about as portable as it
1134 gets.
1135
1136 (I haven't used it myself, but I haven't heard anybody complaining
1137 about it yet).
1138
1139 AnyEvent::DBI
1140 Executes DBI requests asynchronously in a proxy process for you,
1141 notifying you in an event-based way when the operation is finished.
1142
1122 AnyEvent::HTTPD 1143 AnyEvent::HTTPD
1123 A simple embedded webserver. 1144 A simple embedded webserver.
1124 1145
1125 AnyEvent::FastPing 1146 AnyEvent::FastPing
1126 The fastest ping in the west. 1147 The fastest ping in the west.
1127 1148
1128 Coro 1149 Coro
1129 Has special support for AnyEvent via Coro::AnyEvent. 1150 Has special support for AnyEvent via Coro::AnyEvent, which allows
1151 you to simply invert the flow control - don't call us, we will call
1152 you:
1153
1154 async {
1155 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1156 print "5 seconds later!\n";
1157
1158 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1159 my $line = <STDIN>; # works for ttys
1160
1161 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1162 my ($body, $hdr) = Coro::rouse_wait;
1163 };
1130 1164
1131SIMPLIFIED AE API 1165SIMPLIFIED AE API
1132 Starting with version 5.0, AnyEvent officially supports a second, much 1166 Starting with version 5.0, AnyEvent officially supports a second, much
1133 simpler, API that is designed to reduce the calling, typing and memory 1167 simpler, API that is designed to reduce the calling, typing and memory
1134 overhead by using function call syntax and a fixed number of parameters. 1168 overhead by using function call syntax and a fixed number of parameters.
1150 The pure perl event loop simply re-throws the exception (usually within 1184 The pure perl event loop simply re-throws the exception (usually within
1151 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 1185 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1152 Glib uses "install_exception_handler" and so on. 1186 Glib uses "install_exception_handler" and so on.
1153 1187
1154ENVIRONMENT VARIABLES 1188ENVIRONMENT VARIABLES
1155 The following environment variables are used by this module or its 1189 AnyEvent supports a number of environment variables that tune the
1156 submodules. 1190 runtime behaviour. They are usually evaluated when AnyEvent is loaded,
1191 initialised, or a submodule that uses them is loaded. Many of them also
1192 cause AnyEvent to load additional modules - for example,
1193 "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be
1194 loaded.
1157 1195
1158 Note that AnyEvent will remove *all* environment variables starting with 1196 All the environment variables documented here start with
1159 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is 1197 "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace.
1160 enabled. 1198 Other modules are encouraged (but by no means required) to use
1199 "PERL_ANYEVENT_SUBMODULE" if they have registered the
1200 AnyEvent::Submodule namespace on CPAN, for any submodule. For example,
1201 AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it
1202 should not access env variables starting with "AE_", see below).
1203
1204 All variables can also be set via the "AE_" prefix, that is, instead of
1205 setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case
1206 there is a clash btween anyevent and another program that uses
1207 "AE_something" you can set the corresponding "PERL_ANYEVENT_something"
1208 variable to the empty string, as those variables take precedence.
1209
1210 When AnyEvent is first loaded, it copies all "AE_xxx" env variables to
1211 their "PERL_ANYEVENT_xxx" counterpart unless that variable already
1212 exists. If taint mode is on, then AnyEvent will remove *all* environment
1213 variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with
1214 "undef" or the empty string, if the corresaponding "AE_" variable is
1215 set).
1216
1217 The exact algorithm is currently:
1218
1219 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
1220 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
1221 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
1222
1223 This ensures that child processes will not see the "AE_" variables.
1224
1225 The following environment variables are currently known to AnyEvent:
1161 1226
1162 "PERL_ANYEVENT_VERBOSE" 1227 "PERL_ANYEVENT_VERBOSE"
1163 By default, AnyEvent will be completely silent except in fatal 1228 By default, AnyEvent will log messages with loglevel 4 ("error") or
1164 conditions. You can set this environment variable to make AnyEvent 1229 higher (see AnyEvent::Log). You can set this environment variable to
1165 more talkative. 1230 a numerical loglevel to make AnyEvent more (or less) talkative.
1166 1231
1232 If you want to do more than just set the global logging level you
1233 should have a look at "PERL_ANYEVENT_LOG", which allows much more
1234 complex specifications.
1235
1236 When set to 0 ("off"), then no messages whatsoever will be logged
1237 with everything else at defaults.
1238
1167 When set to 1 or higher, causes AnyEvent to warn about unexpected 1239 When set to 5 or higher ("warn"), AnyEvent warns about unexpected
1168 conditions, such as not being able to load the event model specified 1240 conditions, such as not being able to load the event model specified
1169 by "PERL_ANYEVENT_MODEL". 1241 by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
1242 - this is the minimum recommended level for use during development.
1170 1243
1171 When set to 2 or higher, cause AnyEvent to report to STDERR which 1244 When set to 7 or higher (info), AnyEvent reports which event model
1172 event model it chooses. 1245 it chooses.
1173 1246
1174 When set to 8 or higher, then AnyEvent will report extra information 1247 When set to 8 or higher (debug), then AnyEvent will report extra
1175 on which optional modules it loads and how it implements certain 1248 information on which optional modules it loads and how it implements
1176 features. 1249 certain features.
1250
1251 "PERL_ANYEVENT_LOG"
1252 Accepts rather complex logging specifications. For example, you
1253 could log all "debug" messages of some module to stderr, warnings
1254 and above to stderr, and errors and above to syslog, with:
1255
1256 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
1257
1258 For the rather extensive details, see AnyEvent::Log.
1259
1260 This variable is evaluated when AnyEvent (or AnyEvent::Log) is
1261 loaded, so will take effect even before AnyEvent has initialised
1262 itself.
1263
1264 Note that specifying this environment variable causes the
1265 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
1266 does not, so only using the latter saves a few hundred kB of memory
1267 unless a module explicitly needs the extra features of
1268 AnyEvent::Log.
1177 1269
1178 "PERL_ANYEVENT_STRICT" 1270 "PERL_ANYEVENT_STRICT"
1179 AnyEvent does not do much argument checking by default, as thorough 1271 AnyEvent does not do much argument checking by default, as thorough
1180 argument checking is very costly. Setting this variable to a true 1272 argument checking is very costly. Setting this variable to a true
1181 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1273 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1188 is definitely recommended to keep it off in production. Keeping 1280 is definitely recommended to keep it off in production. Keeping
1189 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1281 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1190 programs can be very useful, however. 1282 programs can be very useful, however.
1191 1283
1192 "PERL_ANYEVENT_DEBUG_SHELL" 1284 "PERL_ANYEVENT_DEBUG_SHELL"
1193 If this env variable is set, then its contents will be interpreted 1285 If this env variable is nonempty, then its contents will be
1194 by "AnyEvent::Socket::parse_hostport" (after replacing every 1286 interpreted by "AnyEvent::Socket::parse_hostport" and
1195 occurance of $$ by the process pid) and an "AnyEvent::Debug::shell" 1287 "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
1196 is bound on that port. The shell object is saved in 1288 the process pid). The shell object is saved in
1197 $AnyEvent::Debug::SHELL. 1289 $AnyEvent::Debug::SHELL.
1198 1290
1199 This takes place when the first watcher is created. 1291 This happens when the first watcher is created.
1200 1292
1201 For example, to bind a debug shell on a unix domain socket in 1293 For example, to bind a debug shell on a unix domain socket in
1202 /tmp/debug<pid>.sock, you could use this: 1294 /tmp/debug<pid>.sock, you could use this:
1203 1295
1204 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug\$\$.sock perlprog 1296 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1297 # connect with e.g.: socat readline /tmp/debug123.sock
1205 1298
1299 Or to bind to tcp port 4545 on localhost:
1300
1301 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
1302 # connect with e.g.: telnet localhost 4545
1303
1206 Note that creating sockets in /tmp is very unsafe on multiuser 1304 Note that creating sockets in /tmp or on localhost is very unsafe on
1207 systems. 1305 multiuser systems.
1208 1306
1209 "PERL_ANYEVENT_DEBUG_WRAP" 1307 "PERL_ANYEVENT_DEBUG_WRAP"
1210 Can be set to 0, 1 or 2 and enables wrapping of all watchers for 1308 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1211 debugging purposes. See "AnyEvent::Debug::wrap" for details. 1309 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1212 1310
1227 1325
1228 For example, to force the pure perl model (AnyEvent::Loop::Perl) you 1326 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1229 could start your program like this: 1327 could start your program like this:
1230 1328
1231 PERL_ANYEVENT_MODEL=Perl perl ... 1329 PERL_ANYEVENT_MODEL=Perl perl ...
1330
1331 "PERL_ANYEVENT_IO_MODEL"
1332 The current file I/O model - see AnyEvent::IO for more info.
1333
1334 At the moment, only "Perl" (small, pure-perl, synchronous) and
1335 "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
1336 if AnyEvent::AIO can be loaded, otherwise it is "Perl".
1232 1337
1233 "PERL_ANYEVENT_PROTOCOLS" 1338 "PERL_ANYEVENT_PROTOCOLS"
1234 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 1339 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1235 preferences for IPv4 or IPv6. The default is unspecified (and might 1340 preferences for IPv4 or IPv6. The default is unspecified (and might
1236 change, or be the result of auto probing). 1341 change, or be the result of auto probing).
1250 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1355 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1251 resolve or contact IPv6 addresses. 1356 resolve or contact IPv6 addresses.
1252 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but 1357 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1253 prefer IPv6 over IPv4. 1358 prefer IPv6 over IPv4.
1254 1359
1360 "PERL_ANYEVENT_HOSTS"
1361 This variable, if specified, overrides the /etc/hosts file used by
1362 AnyEvent::Socket"::resolve_sockaddr", i.e. hosts aliases will be
1363 read from that file instead.
1364
1255 "PERL_ANYEVENT_EDNS0" 1365 "PERL_ANYEVENT_EDNS0"
1256 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension 1366 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1257 for DNS. This extension is generally useful to reduce DNS traffic, 1367 for DNS. This extension is generally useful to reduce DNS traffic,
1258 but some (broken) firewalls drop such DNS packets, which is why it 1368 especially when DNSSEC is involved, but some (broken) firewalls drop
1259 is off by default. 1369 such DNS packets, which is why it is off by default.
1260 1370
1261 Setting this variable to 1 will cause AnyEvent::DNS to announce 1371 Setting this variable to 1 will cause AnyEvent::DNS to announce
1262 EDNS0 in its DNS requests. 1372 EDNS0 in its DNS requests.
1263 1373
1264 "PERL_ANYEVENT_MAX_FORKS" 1374 "PERL_ANYEVENT_MAX_FORKS"
1268 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" 1378 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1269 The default value for the "max_outstanding" parameter for the 1379 The default value for the "max_outstanding" parameter for the
1270 default DNS resolver - this is the maximum number of parallel DNS 1380 default DNS resolver - this is the maximum number of parallel DNS
1271 requests that are sent to the DNS server. 1381 requests that are sent to the DNS server.
1272 1382
1383 "PERL_ANYEVENT_MAX_SIGNAL_LATENCY"
1384 Perl has inherently racy signal handling (you can basically choose
1385 between losing signals and memory corruption) - pure perl event
1386 loops (including "AnyEvent::Loop", when "Async::Interrupt" isn't
1387 available) therefore have to poll regularly to avoid losing signals.
1388
1389 Some event loops are racy, but don't poll regularly, and some event
1390 loops are written in C but are still racy. For those event loops,
1391 AnyEvent installs a timer that regularly wakes up the event loop.
1392
1393 By default, the interval for this timer is 10 seconds, but you can
1394 override this delay with this environment variable (or by setting
1395 the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
1396 watchers).
1397
1398 Lower values increase CPU (and energy) usage, higher values can
1399 introduce long delays when reaping children or waiting for signals.
1400
1401 The AnyEvent::Async module, if available, will be used to avoid this
1402 polling (with most event loops).
1403
1273 "PERL_ANYEVENT_RESOLV_CONF" 1404 "PERL_ANYEVENT_RESOLV_CONF"
1274 The file to use instead of /etc/resolv.conf (or OS-specific 1405 The absolute path to a resolv.conf-style file to use instead of
1275 configuration) in the default resolver. When set to the empty 1406 /etc/resolv.conf (or the OS-specific configuration) in the default
1276 string, no default config will be used. 1407 resolver, or the empty string to select the default configuration.
1277 1408
1278 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". 1409 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1279 When neither "ca_file" nor "ca_path" was specified during 1410 When neither "ca_file" nor "ca_path" was specified during
1280 AnyEvent::TLS context creation, and either of these environment 1411 AnyEvent::TLS context creation, and either of these environment
1281 variables exist, they will be used to specify CA certificate 1412 variables are nonempty, they will be used to specify CA certificate
1282 locations instead of a system-dependent default. 1413 locations instead of a system-dependent default.
1283 1414
1284 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT" 1415 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1285 When these are set to 1, then the respective modules are not loaded. 1416 When these are set to 1, then the respective modules are not loaded.
1286 Mostly good for testing AnyEvent itself. 1417 Mostly good for testing AnyEvent itself.
1606 when used without AnyEvent), but most event loops have acceptable 1737 when used without AnyEvent), but most event loops have acceptable
1607 performance with or without AnyEvent. 1738 performance with or without AnyEvent.
1608 1739
1609 * The overhead AnyEvent adds is usually much smaller than the overhead 1740 * The overhead AnyEvent adds is usually much smaller than the overhead
1610 of the actual event loop, only with extremely fast event loops such 1741 of the actual event loop, only with extremely fast event loops such
1611 as EV adds AnyEvent significant overhead. 1742 as EV does AnyEvent add significant overhead.
1612 1743
1613 * You should avoid POE like the plague if you want performance or 1744 * You should avoid POE like the plague if you want performance or
1614 reasonable memory usage. 1745 reasonable memory usage.
1615 1746
1616 BENCHMARKING THE LARGE SERVER CASE 1747 BENCHMARKING THE LARGE SERVER CASE
1879 This module is part of perl since release 5.008. It will be used 2010 This module is part of perl since release 5.008. It will be used
1880 when the chosen event library does not come with a timing source of 2011 when the chosen event library does not come with a timing source of
1881 its own. The pure-perl event loop (AnyEvent::Loop) will additionally 2012 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
1882 load it to try to use a monotonic clock for timing stability. 2013 load it to try to use a monotonic clock for timing stability.
1883 2014
2015 AnyEvent::AIO (and IO::AIO)
2016 The default implementation of AnyEvent::IO is to do I/O
2017 synchronously, stopping programs while they access the disk, which
2018 is fine for a lot of programs.
2019
2020 Installing AnyEvent::AIO (and its IO::AIO dependency) makes it
2021 switch to a true asynchronous implementation, so event processing
2022 can continue even while waiting for disk I/O.
2023
1884FORK 2024FORK
1885 Most event libraries are not fork-safe. The ones who are usually are 2025 Most event libraries are not fork-safe. The ones who are usually are
1886 because they rely on inefficient but fork-safe "select" or "poll" calls 2026 because they rely on inefficient but fork-safe "select" or "poll" calls
1887 - higher performance APIs such as BSD's kqueue or the dreaded Linux 2027 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1888 epoll are usually badly thought-out hacks that are incompatible with 2028 epoll are usually badly thought-out hacks that are incompatible with
1942SEE ALSO 2082SEE ALSO
1943 Tutorial/Introduction: AnyEvent::Intro. 2083 Tutorial/Introduction: AnyEvent::Intro.
1944 2084
1945 FAQ: AnyEvent::FAQ. 2085 FAQ: AnyEvent::FAQ.
1946 2086
1947 Utility functions: AnyEvent::Util. 2087 Utility functions: AnyEvent::Util (misc. grab-bag), AnyEvent::Log
2088 (simply logging).
1948 2089
2090 Development/Debugging: AnyEvent::Strict (stricter checking),
2091 AnyEvent::Debug (interactive shell, watcher tracing).
2092
1949 Event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, 2093 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
1950 Glib::Event, Glib, Tk, Event::Lib, Qt, POE. 2094 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK.
1951 2095
1952 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 2096 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1953 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 2097 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1954 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 2098 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1955 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi. 2099 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK.
1956 2100
1957 Non-blocking file handles, sockets, TCP clients and servers: 2101 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
1958 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 2102 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
2103
2104 Asynchronous File I/O: AnyEvent::IO.
1959 2105
1960 Asynchronous DNS: AnyEvent::DNS. 2106 Asynchronous DNS: AnyEvent::DNS.
1961 2107
1962 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event. 2108 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1963 2109
1964 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC, 2110 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1965 AnyEvent::HTTP. 2111 AnyEvent::HTTP.
1966 2112
1967AUTHOR 2113AUTHOR
1968 Marc Lehmann <schmorp@schmorp.de> 2114 Marc Lehmann <schmorp@schmorp.de>
1969 http://home.schmorp.de/ 2115 http://anyevent.schmorp.de
1970 2116

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines