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

Comparing AnyEvent/README (file contents):
Revision 1.67 by root, Fri Aug 26 05:33:53 2011 UTC vs.
Revision 1.79 by root, Tue Feb 26 02:08:34 2019 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.
815 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.
829
816SUPPORTED EVENT LOOPS/BACKENDS 830SUPPORTED EVENT LOOPS/BACKENDS
817 The available backend classes are (every class has its own manpage): 831 The following backend classes are part of the AnyEvent distribution
832 (every class has its own manpage):
818 833
819 Backends that are autoprobed when no other event loop can be found. 834 Backends that are autoprobed when no other event loop can be found.
820 EV is the preferred backend when no other event loop seems to be in 835 EV is the preferred backend when no other event loop seems to be in
821 use. If EV is not installed, then AnyEvent will fall back to its own 836 use. If EV is not installed, then AnyEvent will fall back to its own
822 pure-perl implementation, which is available everywhere as it comes 837 pure-perl implementation, which is available everywhere as it comes
… …
834 by the main program. 849 by the main program.
835 850
836 AnyEvent::Impl::Event based on Event, very stable, few glitches. 851 AnyEvent::Impl::Event based on Event, very stable, few glitches.
837 AnyEvent::Impl::Glib based on Glib, slow but very stable. 852 AnyEvent::Impl::Glib based on Glib, slow but very stable.
838 AnyEvent::Impl::Tk based on Tk, very broken. 853 AnyEvent::Impl::Tk based on Tk, very broken.
854 AnyEvent::Impl::UV based on UV, innovated square wheels.
839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 855 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
840 AnyEvent::Impl::POE based on POE, very slow, some limitations. 856 AnyEvent::Impl::POE based on POE, very slow, some limitations.
841 AnyEvent::Impl::Irssi used when running within irssi. 857 AnyEvent::Impl::Irssi used when running within irssi.
842 AnyEvent::Impl::IOAsync based on IO::Async. 858 AnyEvent::Impl::IOAsync based on IO::Async.
843 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 859 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
844 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 860 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
845 861
846 Backends with special needs. 862 Backends with special needs.
847 Qt requires the Qt::Application to be instantiated first, but will 863 Qt requires the Qt::Application to be instantiated first, but will
848 otherwise be picked up automatically. As long as the main program 864 otherwise be picked up automatically. As long as the main program
849 instantiates the application before any AnyEvent watchers are 865 instantiates the application before any AnyEvent watchers are
… …
865 POE backend, so it can be supported through POE. 881 POE backend, so it can be supported through POE.
866 882
867 AnyEvent knows about both Prima and Wx, however, and will try to 883 AnyEvent knows about both Prima and Wx, however, and will try to
868 load POE when detecting them, in the hope that POE will pick them 884 load POE when detecting them, in the hope that POE will pick them
869 up, in which case everything will be automatic. 885 up, in which case everything will be automatic.
886
887 Known event loops outside the AnyEvent distribution
888 The following event loops or programs support AnyEvent by providing
889 their own AnyEvent backend. They will be picked up automatically.
890
891 urxvt::anyevent available to rxvt-unicode extensions
870 892
871GLOBAL VARIABLES AND FUNCTIONS 893GLOBAL VARIABLES AND FUNCTIONS
872 These are not normally required to use AnyEvent, but can be useful to 894 These are not normally required to use AnyEvent, but can be useful to
873 write AnyEvent extension modules. 895 write AnyEvent extension modules.
874 896
… …
899 $guard = AnyEvent::post_detect { BLOCK } 921 $guard = AnyEvent::post_detect { BLOCK }
900 Arranges for the code block to be executed as soon as the event 922 Arranges for the code block to be executed as soon as the event
901 model is autodetected (or immediately if that has already happened). 923 model is autodetected (or immediately if that has already happened).
902 924
903 The block will be executed *after* the actual backend has been 925 The block will be executed *after* the actual backend has been
904 detected ($AnyEvent::MODEL is set), but *before* any watchers have 926 detected ($AnyEvent::MODEL is set), so it is possible to do some
905 been created, so it is possible to e.g. patch @AnyEvent::ISA or do 927 initialisation only when AnyEvent is actually initialised - see the
906 other initialisations - see the sources of AnyEvent::Strict or
907 AnyEvent::AIO to see how this is used. 928 sources of AnyEvent::AIO to see how this is used.
908 929
909 The most common usage is to create some global watchers, without 930 The most common usage is to create some global watchers, without
910 forcing event module detection too early, for example, AnyEvent::AIO 931 forcing event module detection too early. For example, AnyEvent::AIO
911 creates and installs the global IO::AIO watcher in a "post_detect" 932 creates and installs the global IO::AIO watcher in a "post_detect"
912 block to avoid autodetecting the event module at load time. 933 block to avoid autodetecting the event module at load time.
913 934
914 If called in scalar or list context, then it creates and returns an 935 If called in scalar or list context, then it creates and returns an
915 object that automatically removes the callback again when it is 936 object that automatically removes the callback again when it is
… …
931 # able to just C<undef $WATCHER> if the watcher causes them grief. 952 # able to just C<undef $WATCHER> if the watcher causes them grief.
932 953
933 $WATCHER ||= $guard; 954 $WATCHER ||= $guard;
934 955
935 @AnyEvent::post_detect 956 @AnyEvent::post_detect
936 If there are any code references in this array (you can "push" to it 957 This is a lower level interface then "AnyEvent::post_detect" (the
937 before or after loading AnyEvent), then they will be called directly 958 function). This variable is mainly useful for modules that can do
959 something useful when AnyEvent is used and thus want to know when it
960 is initialised, but do not need to even load it by default. This
961 array provides the means to hook into AnyEvent passively, without
962 loading it.
963
964 Here is how it works: If there are any code references in this array
965 (you can "push" to it before or after loading AnyEvent), then they
938 after the event loop has been chosen. 966 will be called directly after the event loop has been chosen.
939 967
940 You should check $AnyEvent::MODEL before adding to this array, 968 You should check $AnyEvent::MODEL before adding to this array,
941 though: if it is defined then the event loop has already been 969 though: if it is defined then the event loop has already been
942 detected, and the array will be ignored. 970 detected, and the array will be ignored.
943 971
944 Best use "AnyEvent::post_detect { BLOCK }" when your application 972 Best use "AnyEvent::post_detect { BLOCK }" when your application
945 allows it, as it takes care of these details. 973 allows it, as it takes care of these details.
946
947 This variable is mainly useful for modules that can do something
948 useful when AnyEvent is used and thus want to know when it is
949 initialised, but do not need to even load it by default. This array
950 provides the means to hook into AnyEvent passively, without loading
951 it.
952 974
953 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used 975 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
954 together, you could put this into Coro (this is the actual code used 976 together, you could put this into Coro (this is the actual code used
955 by Coro to accomplish this): 977 by Coro to accomplish this):
956 978
… …
975 To understand the usefulness of this function, consider a function 997 To understand the usefulness of this function, consider a function
976 that asynchronously does something for you and returns some 998 that asynchronously does something for you and returns some
977 transaction object or guard to let you cancel the operation. For 999 transaction object or guard to let you cancel the operation. For
978 example, "AnyEvent::Socket::tcp_connect": 1000 example, "AnyEvent::Socket::tcp_connect":
979 1001
980 # start a conenction attempt unless one is active 1002 # start a connection attempt unless one is active
981 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { 1003 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
982 delete $self->{connect_guard}; 1004 delete $self->{connect_guard};
983 ... 1005 ...
984 }; 1006 };
985 1007
… …
1010 If AnyEvent::Log is not loaded then this function makes a simple 1032 If AnyEvent::Log is not loaded then this function makes a simple
1011 test to see whether the message will be logged. If the test succeeds 1033 test to see whether the message will be logged. If the test succeeds
1012 it will load AnyEvent::Log and call "AnyEvent::Log::log" - 1034 it will load AnyEvent::Log and call "AnyEvent::Log::log" -
1013 consequently, look at the AnyEvent::Log documentation for details. 1035 consequently, look at the AnyEvent::Log documentation for details.
1014 1036
1015 If the test fails it will simply return. 1037 If the test fails it will simply return. Right now this happens when
1038 a numerical loglevel is used and it is larger than the level
1039 specified via $ENV{PERL_ANYEVENT_VERBOSE}.
1016 1040
1017 If you want to sprinkle loads of logging calls around your code, 1041 If you want to sprinkle loads of logging calls around your code,
1018 consider creating a logger callback with the "AnyEvent::Log::logger" 1042 consider creating a logger callback with the "AnyEvent::Log::logger"
1019 function, which can reduce typing, codesize and can reduce the 1043 function, which can reduce typing, codesize and can reduce the
1020 logging overhead enourmously. 1044 logging overhead enourmously.
1045
1046 AnyEvent::fh_block $filehandle
1047 AnyEvent::fh_unblock $filehandle
1048 Sets blocking or non-blocking behaviour for the given filehandle.
1021 1049
1022WHAT TO DO IN A MODULE 1050WHAT TO DO IN A MODULE
1023 As a module author, you should "use AnyEvent" and call AnyEvent methods 1051 As a module author, you should "use AnyEvent" and call AnyEvent methods
1024 freely, but you should not load a specific event module or rely on it. 1052 freely, but you should not load a specific event module or rely on it.
1025 1053
… …
1084 modules come as part of AnyEvent, the others are available via CPAN (see 1112 modules come as part of AnyEvent, the others are available via CPAN (see
1085 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer 1113 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer
1086 non-exhaustive list), and the list is heavily biased towards modules of 1114 non-exhaustive list), and the list is heavily biased towards modules of
1087 the AnyEvent author himself :) 1115 the AnyEvent author himself :)
1088 1116
1089 AnyEvent::Util 1117 AnyEvent::Util (part of the AnyEvent distribution)
1090 Contains various utility functions that replace often-used blocking 1118 Contains various utility functions that replace often-used blocking
1091 functions such as "inet_aton" with event/callback-based versions. 1119 functions such as "inet_aton" with event/callback-based versions.
1092 1120
1093 AnyEvent::Socket 1121 AnyEvent::Socket (part of the AnyEvent distribution)
1094 Provides various utility functions for (internet protocol) sockets, 1122 Provides various utility functions for (internet protocol) sockets,
1095 addresses and name resolution. Also functions to create non-blocking 1123 addresses and name resolution. Also functions to create non-blocking
1096 tcp connections or tcp servers, with IPv6 and SRV record support and 1124 tcp connections or tcp servers, with IPv6 and SRV record support and
1097 more. 1125 more.
1098 1126
1099 AnyEvent::Handle 1127 AnyEvent::Handle (part of the AnyEvent distribution)
1100 Provide read and write buffers, manages watchers for reads and 1128 Provide read and write buffers, manages watchers for reads and
1101 writes, supports raw and formatted I/O, I/O queued and fully 1129 writes, supports raw and formatted I/O, I/O queued and fully
1102 transparent and non-blocking SSL/TLS (via AnyEvent::TLS). 1130 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1103 1131
1104 AnyEvent::DNS 1132 AnyEvent::DNS (part of the AnyEvent distribution)
1105 Provides rich asynchronous DNS resolver capabilities. 1133 Provides rich asynchronous DNS resolver capabilities.
1106 1134
1107 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1135 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1108 AnyEvent::IGS, AnyEvent::FCP 1136 AnyEvent::IGS, AnyEvent::FCP
1109 Implement event-based interfaces to the protocols of the same name 1137 Implement event-based interfaces to the protocols of the same name
1110 (for the curious, IGS is the International Go Server and FCP is the 1138 (for the curious, IGS is the International Go Server and FCP is the
1111 Freenet Client Protocol). 1139 Freenet Client Protocol).
1112 1140
1113 AnyEvent::AIO 1141 AnyEvent::AIO (part of the AnyEvent distribution)
1114 Truly asynchronous (as opposed to non-blocking) I/O, should be in 1142 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1115 the toolbox of every event programmer. AnyEvent::AIO transparently 1143 the toolbox of every event programmer. AnyEvent::AIO transparently
1116 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1144 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1117 event-based file I/O, and much more. 1145 event-based file I/O, and much more.
1146
1147 AnyEvent::Fork, AnyEvent::Fork::RPC, AnyEvent::Fork::Pool,
1148 AnyEvent::Fork::Remote
1149 These let you safely fork new subprocesses, either locally or
1150 remotely (e.g.v ia ssh), using some RPC protocol or not, without the
1151 limitations normally imposed by fork (AnyEvent works fine for
1152 example). Dynamically-resized worker pools are obviously included as
1153 well.
1154
1155 And they are quite tiny and fast as well - "abusing" AnyEvent::Fork
1156 just to exec external programs can easily beat using "fork" and
1157 "exec" (or even "system") in most programs.
1118 1158
1119 AnyEvent::Filesys::Notify 1159 AnyEvent::Filesys::Notify
1120 AnyEvent is good for non-blocking stuff, but it can't detect file or 1160 AnyEvent is good for non-blocking stuff, but it can't detect file or
1121 path changes (e.g. "watch this directory for new files", "watch this 1161 path changes (e.g. "watch this directory for new files", "watch this
1122 file for changes"). The AnyEvent::Filesys::Notify module promises to 1162 file for changes"). The AnyEvent::Filesys::Notify module promises to
… …
1124 and some weird, without doubt broken, stuff on OS X to monitor 1164 and some weird, without doubt broken, stuff on OS X to monitor
1125 files. It can fall back to blocking scans at regular intervals 1165 files. It can fall back to blocking scans at regular intervals
1126 transparently on other platforms, so it's about as portable as it 1166 transparently on other platforms, so it's about as portable as it
1127 gets. 1167 gets.
1128 1168
1129 (I haven't used it myself, but I haven't heard anybody complaining 1169 (I haven't used it myself, but it seems the biggest problem with it
1130 about it yet). 1170 is it quite bad performance).
1131 1171
1132 AnyEvent::DBI 1172 AnyEvent::DBI
1133 Executes DBI requests asynchronously in a proxy process for you, 1173 Executes DBI requests asynchronously in a proxy process for you,
1134 notifying you in an event-based way when the operation is finished. 1174 notifying you in an event-based way when the operation is finished.
1135
1136 AnyEvent::HTTPD
1137 A simple embedded webserver.
1138 1175
1139 AnyEvent::FastPing 1176 AnyEvent::FastPing
1140 The fastest ping in the west. 1177 The fastest ping in the west.
1141 1178
1142 Coro 1179 Coro
… …
1216 This ensures that child processes will not see the "AE_" variables. 1253 This ensures that child processes will not see the "AE_" variables.
1217 1254
1218 The following environment variables are currently known to AnyEvent: 1255 The following environment variables are currently known to AnyEvent:
1219 1256
1220 "PERL_ANYEVENT_VERBOSE" 1257 "PERL_ANYEVENT_VERBOSE"
1221 By default, AnyEvent will be completely silent except in fatal 1258 By default, AnyEvent will log messages with loglevel 4 ("error") or
1222 conditions. You can set this environment variable to make AnyEvent 1259 higher (see AnyEvent::Log). You can set this environment variable to
1223 more talkative. If you want to do more than just set the global 1260 a numerical loglevel to make AnyEvent more (or less) talkative.
1261
1262 If you want to do more than just set the global logging level you
1224 logging level you should have a look at "PERL_ANYEVENT_LOG", which 1263 should have a look at "PERL_ANYEVENT_LOG", which allows much more
1225 allows much more complex specifications. 1264 complex specifications.
1226 1265
1266 When set to 0 ("off"), then no messages whatsoever will be logged
1267 with everything else at defaults.
1268
1227 When set to 5 or higher (warn), causes AnyEvent to warn about 1269 When set to 5 or higher ("warn"), AnyEvent warns about unexpected
1228 unexpected conditions, such as not being able to load the event 1270 conditions, such as not being able to load the event model specified
1229 model specified by "PERL_ANYEVENT_MODEL", or a guard callback 1271 by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
1230 throwing an exception - this is the minimum recommended level. 1272 - this is the minimum recommended level for use during development.
1231 1273
1232 When set to 7 or higher (info), cause AnyEvent to report which event 1274 When set to 7 or higher (info), AnyEvent reports which event model
1233 model it chooses. 1275 it chooses.
1234 1276
1235 When set to 8 or higher (debug), then AnyEvent will report extra 1277 When set to 8 or higher (debug), then AnyEvent will report extra
1236 information on which optional modules it loads and how it implements 1278 information on which optional modules it loads and how it implements
1237 certain features. 1279 certain features.
1238 1280
… …
1250 itself. 1292 itself.
1251 1293
1252 Note that specifying this environment variable causes the 1294 Note that specifying this environment variable causes the
1253 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE" 1295 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
1254 does not, so only using the latter saves a few hundred kB of memory 1296 does not, so only using the latter saves a few hundred kB of memory
1255 until the first message is being logged. 1297 unless a module explicitly needs the extra features of
1298 AnyEvent::Log.
1256 1299
1257 "PERL_ANYEVENT_STRICT" 1300 "PERL_ANYEVENT_STRICT"
1258 AnyEvent does not do much argument checking by default, as thorough 1301 AnyEvent does not do much argument checking by default, as thorough
1259 argument checking is very costly. Setting this variable to a true 1302 argument checking is very costly. Setting this variable to a true
1260 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1303 value will cause AnyEvent to load "AnyEvent::Strict" and then to
… …
1267 is definitely recommended to keep it off in production. Keeping 1310 is definitely recommended to keep it off in production. Keeping
1268 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1311 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1269 programs can be very useful, however. 1312 programs can be very useful, however.
1270 1313
1271 "PERL_ANYEVENT_DEBUG_SHELL" 1314 "PERL_ANYEVENT_DEBUG_SHELL"
1272 If this env variable is set, then its contents will be interpreted 1315 If this env variable is nonempty, then its contents will be
1273 by "AnyEvent::Socket::parse_hostport" (after replacing every 1316 interpreted by "AnyEvent::Socket::parse_hostport" and
1274 occurance of $$ by the process pid) and an "AnyEvent::Debug::shell" 1317 "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
1275 is bound on that port. The shell object is saved in 1318 the process pid). The shell object is saved in
1276 $AnyEvent::Debug::SHELL. 1319 $AnyEvent::Debug::SHELL.
1277 1320
1278 This happens when the first watcher is created. 1321 This happens when the first watcher is created.
1279 1322
1280 For example, to bind a debug shell on a unix domain socket in 1323 For example, to bind a debug shell on a unix domain socket in
1281 /tmp/debug<pid>.sock, you could use this: 1324 /tmp/debug<pid>.sock, you could use this:
1282 1325
1283 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 1326 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1327 # connect with e.g.: socat readline /tmp/debug123.sock
1284 1328
1329 Or to bind to tcp port 4545 on localhost:
1330
1331 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
1332 # connect with e.g.: telnet localhost 4545
1333
1285 Note that creating sockets in /tmp is very unsafe on multiuser 1334 Note that creating sockets in /tmp or on localhost is very unsafe on
1286 systems. 1335 multiuser systems.
1287 1336
1288 "PERL_ANYEVENT_DEBUG_WRAP" 1337 "PERL_ANYEVENT_DEBUG_WRAP"
1289 Can be set to 0, 1 or 2 and enables wrapping of all watchers for 1338 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1290 debugging purposes. See "AnyEvent::Debug::wrap" for details. 1339 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1291 1340
… …
1307 For example, to force the pure perl model (AnyEvent::Loop::Perl) you 1356 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1308 could start your program like this: 1357 could start your program like this:
1309 1358
1310 PERL_ANYEVENT_MODEL=Perl perl ... 1359 PERL_ANYEVENT_MODEL=Perl perl ...
1311 1360
1361 "PERL_ANYEVENT_IO_MODEL"
1362 The current file I/O model - see AnyEvent::IO for more info.
1363
1364 At the moment, only "Perl" (small, pure-perl, synchronous) and
1365 "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
1366 if AnyEvent::AIO can be loaded, otherwise it is "Perl".
1367
1312 "PERL_ANYEVENT_PROTOCOLS" 1368 "PERL_ANYEVENT_PROTOCOLS"
1313 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 1369 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1314 preferences for IPv4 or IPv6. The default is unspecified (and might 1370 preferences for IPv4 or IPv6. The default is unspecified (and might
1315 change, or be the result of auto probing). 1371 change, or be the result of auto probing).
1316 1372
… …
1319 mentioned will be used, and preference will be given to protocols 1375 mentioned will be used, and preference will be given to protocols
1320 mentioned earlier in the list. 1376 mentioned earlier in the list.
1321 1377
1322 This variable can effectively be used for denial-of-service attacks 1378 This variable can effectively be used for denial-of-service attacks
1323 against local programs (e.g. when setuid), although the impact is 1379 against local programs (e.g. when setuid), although the impact is
1324 likely small, as the program has to handle conenction and other 1380 likely small, as the program has to handle connection and other
1325 failures anyways. 1381 failures anyways.
1326 1382
1327 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 1383 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1328 IPv6, but support both and try to use both. 1384 IPv6, but support both and try to use both.
1329 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1385 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
… …
1351 1407
1352 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" 1408 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1353 The default value for the "max_outstanding" parameter for the 1409 The default value for the "max_outstanding" parameter for the
1354 default DNS resolver - this is the maximum number of parallel DNS 1410 default DNS resolver - this is the maximum number of parallel DNS
1355 requests that are sent to the DNS server. 1411 requests that are sent to the DNS server.
1412
1413 "PERL_ANYEVENT_MAX_SIGNAL_LATENCY"
1414 Perl has inherently racy signal handling (you can basically choose
1415 between losing signals and memory corruption) - pure perl event
1416 loops (including "AnyEvent::Loop", when "Async::Interrupt" isn't
1417 available) therefore have to poll regularly to avoid losing signals.
1418
1419 Some event loops are racy, but don't poll regularly, and some event
1420 loops are written in C but are still racy. For those event loops,
1421 AnyEvent installs a timer that regularly wakes up the event loop.
1422
1423 By default, the interval for this timer is 10 seconds, but you can
1424 override this delay with this environment variable (or by setting
1425 the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
1426 watchers).
1427
1428 Lower values increase CPU (and energy) usage, higher values can
1429 introduce long delays when reaping children or waiting for signals.
1430
1431 The AnyEvent::Async module, if available, will be used to avoid this
1432 polling (with most event loops).
1356 1433
1357 "PERL_ANYEVENT_RESOLV_CONF" 1434 "PERL_ANYEVENT_RESOLV_CONF"
1358 The absolute path to a resolv.conf-style file to use instead of 1435 The absolute path to a resolv.conf-style file to use instead of
1359 /etc/resolv.conf (or the OS-specific configuration) in the default 1436 /etc/resolv.conf (or the OS-specific configuration) in the default
1360 resolver, or the empty string to select the default configuration. 1437 resolver, or the empty string to select the default configuration.
… …
1542 my $txn = shift; 1619 my $txn = shift;
1543 my $data = $txn->result; 1620 my $data = $txn->result;
1544 ... 1621 ...
1545 }); 1622 });
1546 1623
1547 EV::loop; 1624 EV::run;
1548 1625
1549 3b. The module user could use AnyEvent, too: 1626 3b. The module user could use AnyEvent, too:
1550 1627
1551 use AnyEvent; 1628 use AnyEvent;
1552 1629
… …
1963 This module is part of perl since release 5.008. It will be used 2040 This module is part of perl since release 5.008. It will be used
1964 when the chosen event library does not come with a timing source of 2041 when the chosen event library does not come with a timing source of
1965 its own. The pure-perl event loop (AnyEvent::Loop) will additionally 2042 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
1966 load it to try to use a monotonic clock for timing stability. 2043 load it to try to use a monotonic clock for timing stability.
1967 2044
2045 AnyEvent::AIO (and IO::AIO)
2046 The default implementation of AnyEvent::IO is to do I/O
2047 synchronously, stopping programs while they access the disk, which
2048 is fine for a lot of programs.
2049
2050 Installing AnyEvent::AIO (and its IO::AIO dependency) makes it
2051 switch to a true asynchronous implementation, so event processing
2052 can continue even while waiting for disk I/O.
2053
1968FORK 2054FORK
1969 Most event libraries are not fork-safe. The ones who are usually are 2055 Most event libraries are not fork-safe. The ones who are usually are
1970 because they rely on inefficient but fork-safe "select" or "poll" calls 2056 because they rely on inefficient but fork-safe "select" or "poll" calls
1971 - higher performance APIs such as BSD's kqueue or the dreaded Linux 2057 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1972 epoll are usually badly thought-out hacks that are incompatible with 2058 epoll are usually badly thought-out hacks that are incompatible with
… …
1979 usually happens when the first AnyEvent watcher is created, or the 2065 usually happens when the first AnyEvent watcher is created, or the
1980 library is loaded). 2066 library is loaded).
1981 2067
1982 If you have to fork, you must either do so *before* creating your first 2068 If you have to fork, you must either do so *before* creating your first
1983 watcher OR you must not use AnyEvent at all in the child OR you must do 2069 watcher OR you must not use AnyEvent at all in the child OR you must do
1984 something completely out of the scope of AnyEvent. 2070 something completely out of the scope of AnyEvent (see below).
1985 2071
1986 The problem of doing event processing in the parent *and* the child is 2072 The problem of doing event processing in the parent *and* the child is
1987 much more complicated: even for backends that *are* fork-aware or 2073 much more complicated: even for backends that *are* fork-aware or
1988 fork-safe, their behaviour is not usually what you want: fork clones all 2074 fork-safe, their behaviour is not usually what you want: fork clones all
1989 watchers, that means all timers, I/O watchers etc. are active in both 2075 watchers, that means all timers, I/O watchers etc. are active in both
1990 parent and child, which is almost never what you want. USing "exec" to 2076 parent and child, which is almost never what you want. Using "exec" to
1991 start worker children from some kind of manage rprocess is usually 2077 start worker children from some kind of manage prrocess is usually
1992 preferred, because it is much easier and cleaner, at the expense of 2078 preferred, because it is much easier and cleaner, at the expense of
1993 having to have another binary. 2079 having to have another binary.
2080
2081 In addition to logical problems with fork, there are also implementation
2082 problems. For example, on POSIX systems, you cannot fork at all in Perl
2083 code if a thread (I am talking of pthreads here) was ever created in the
2084 process, and this is just the tip of the iceberg. In general, using fork
2085 from Perl is difficult, and attempting to use fork without an exec to
2086 implement some kind of parallel processing is almost certainly doomed.
2087
2088 To safely fork and exec, you should use a module such as Proc::FastSpawn
2089 that let's you safely fork and exec new processes.
2090
2091 If you want to do multiprocessing using processes, you can look at the
2092 AnyEvent::Fork module (and some related modules such as
2093 AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote).
2094 This module allows you to safely create subprocesses without any
2095 limitations - you can use X11 toolkits or AnyEvent in the children
2096 created by AnyEvent::Fork safely and without any special precautions.
1994 2097
1995SECURITY CONSIDERATIONS 2098SECURITY CONSIDERATIONS
1996 AnyEvent can be forced to load any event model via 2099 AnyEvent can be forced to load any event model via
1997 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 2100 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1998 to execute arbitrary code or directly gain access, it can easily be used 2101 to execute arbitrary code or directly gain access, it can easily be used
… …
2033 2136
2034 Development/Debugging: AnyEvent::Strict (stricter checking), 2137 Development/Debugging: AnyEvent::Strict (stricter checking),
2035 AnyEvent::Debug (interactive shell, watcher tracing). 2138 AnyEvent::Debug (interactive shell, watcher tracing).
2036 2139
2037 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, 2140 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
2038 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK. 2141 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV.
2039 2142
2040 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 2143 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
2041 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 2144 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
2042 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 2145 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
2043 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK. 2146 AnyEvent::Impl::IOAsync, AnyEvent::Impl::Irssi, AnyEvent::Impl::FLTK,
2147 AnyEvent::Impl::Cocoa, AnyEvent::Impl::UV.
2044 2148
2045 Non-blocking handles, pipes, stream sockets, TCP clients and servers: 2149 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
2046 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 2150 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
2047 2151
2152 Asynchronous File I/O: AnyEvent::IO.
2153
2048 Asynchronous DNS: AnyEvent::DNS. 2154 Asynchronous DNS: AnyEvent::DNS.
2049 2155
2050 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event. 2156 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
2051 2157
2052 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC, 2158 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
2053 AnyEvent::HTTP. 2159 AnyEvent::HTTP.
2054 2160
2055AUTHOR 2161AUTHOR
2056 Marc Lehmann <schmorp@schmorp.de> 2162 Marc Lehmann <schmorp@schmorp.de>
2057 http://home.schmorp.de/ 2163 http://anyevent.schmorp.de
2058 2164

Diff Legend

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