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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.330 by root, Tue Aug 31 00:59:55 2010 UTC vs.
Revision 1.409 by root, Thu Dec 6 12:10:09 2012 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - the DBI of event loop programming 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
6and POE are various supported event loops/environments. 6FLTK and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
46in a tutorial or some gentle introduction, have a look at the 46in a tutorial or some gentle introduction, have a look at the
47L<AnyEvent::Intro> manpage. 47L<AnyEvent::Intro> manpage.
48 48
49=head1 SUPPORT 49=head1 SUPPORT
50 50
51An FAQ document is available as L<AnyEvent::FAQ>.
52
51There is a mailinglist for discussing all things AnyEvent, and an IRC 53There also is a mailinglist for discussing all things AnyEvent, and an IRC
52channel, too. 54channel, too.
53 55
54See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software 56See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
55Repository>, at L<http://anyevent.schmorp.de>, for more info. 57Repository>, at L<http://anyevent.schmorp.de>, for more info.
56 58
83that isn't them. What's worse, all the potential users of your 85that isn't them. What's worse, all the potential users of your
84module are I<also> forced to use the same event loop you use. 86module are I<also> forced to use the same event loop you use.
85 87
86AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 88AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
87fine. AnyEvent + Tk works fine etc. etc. but none of these work together 89fine. AnyEvent + Tk works fine etc. etc. but none of these work together
88with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if 90with the rest: POE + EV? No go. Tk + Event? No go. Again: if your module
89your module uses one of those, every user of your module has to use it, 91uses one of those, every user of your module has to use it, too. But if
90too. But if your module uses AnyEvent, it works transparently with all 92your module uses AnyEvent, it works transparently with all event models it
91event models it supports (including stuff like IO::Async, as long as those 93supports (including stuff like IO::Async, as long as those use one of the
92use one of the supported event loops. It is easy to add new event loops 94supported event loops. It is easy to add new event loops to AnyEvent, too,
93to AnyEvent, too, so it is future-proof). 95so it is future-proof).
94 96
95In addition to being free of having to use I<the one and only true event 97In addition to being free of having to use I<the one and only true event
96model>, AnyEvent also is free of bloat and policy: with POE or similar 98model>, AnyEvent also is free of bloat and policy: with POE or similar
97modules, you get an enormous amount of code and strict rules you have to 99modules, you get an enormous amount of code and strict rules you have to
98follow. AnyEvent, on the other hand, is lean and to the point, by only 100follow. AnyEvent, on the other hand, is lean and to the point, by only
119The interface itself is vaguely similar, but not identical to the L<Event> 121The interface itself is vaguely similar, but not identical to the L<Event>
120module. 122module.
121 123
122During the first call of any watcher-creation method, the module tries 124During the first call of any watcher-creation method, the module tries
123to detect the currently loaded event loop by probing whether one of the 125to detect the currently loaded event loop by probing whether one of the
124following modules is already loaded: L<EV>, 126following modules is already loaded: L<EV>, L<AnyEvent::Loop>,
125L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, 127L<Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. The first one
126L<POE>. The first one found is used. If none are found, the module tries 128found is used. If none are detected, the module tries to load the first
127to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl 129four modules in the order given; but note that if L<EV> is not
128adaptor should always succeed) in the order given. The first one that can 130available, the pure-perl L<AnyEvent::Loop> should always work, so
129be successfully loaded will be used. If, after this, still none could be 131the other two are not normally tried.
130found, AnyEvent will fall back to a pure-perl event loop, which is not
131very efficient, but should work everywhere.
132 132
133Because AnyEvent first checks for modules that are already loaded, loading 133Because AnyEvent first checks for modules that are already loaded, loading
134an event model explicitly before first using AnyEvent will likely make 134an event model explicitly before first using AnyEvent will likely make
135that model the default. For example: 135that model the default. For example:
136 136
142The I<likely> means that, if any module loads another event model and 142The I<likely> means that, if any module loads another event model and
143starts using it, all bets are off - this case should be very rare though, 143starts using it, all bets are off - this case should be very rare though,
144as very few modules hardcode event loops without announcing this very 144as very few modules hardcode event loops without announcing this very
145loudly. 145loudly.
146 146
147The pure-perl implementation of AnyEvent is called 147The pure-perl implementation of AnyEvent is called C<AnyEvent::Loop>. Like
148C<AnyEvent::Impl::Perl>. Like other event modules you can load it 148other event modules you can load it explicitly and enjoy the high
149explicitly and enjoy the high availability of that event loop :) 149availability of that event loop :)
150 150
151=head1 WATCHERS 151=head1 WATCHERS
152 152
153AnyEvent has the central concept of a I<watcher>, which is an object that 153AnyEvent has the central concept of a I<watcher>, which is an object that
154stores relevant data for each kind of event you are waiting for, such as 154stores relevant data for each kind of event you are waiting for, such as
356difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into 356difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
357account. 357account.
358 358
359=item AnyEvent->now_update 359=item AnyEvent->now_update
360 360
361Some event loops (such as L<EV> or L<AnyEvent::Impl::Perl>) cache 361Some event loops (such as L<EV> or L<AnyEvent::Loop>) cache the current
362the current time for each loop iteration (see the discussion of L<< 362time for each loop iteration (see the discussion of L<< AnyEvent->now >>,
363AnyEvent->now >>, above). 363above).
364 364
365When a callback runs for a long time (or when the process sleeps), then 365When a callback runs for a long time (or when the process sleeps), then
366this "current" time will differ substantially from the real time, which 366this "current" time will differ substantially from the real time, which
367might affect timers and time-outs. 367might affect timers and time-outs.
368 368
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's 415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation). 416pure perl implementation).
417 417
418=head3 Safe/Unsafe Signals 418=head3 Safe/Unsafe Signals
419 419
420Perl signals can be either "safe" (synchronous to opcode handling) or 420Perl signals can be either "safe" (synchronous to opcode handling)
421"unsafe" (asynchronous) - the former might get delayed indefinitely, the 421or "unsafe" (asynchronous) - the former might delay signal delivery
422latter might corrupt your memory. 422indefinitely, the latter might corrupt your memory.
423 423
424AnyEvent signal handlers are, in addition, synchronous to the event loop, 424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be 425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc. 426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too). 427callbacks, too).
428 428
429=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
430 430
431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
432callbacks to signals in a generic way, which is a pity, as you cannot 432attaching callbacks to signals in a generic way, which is a pity,
433do race-free signal handling in perl, requiring C libraries for 433as you cannot do race-free signal handling in perl, requiring
434this. AnyEvent will try to do its best, which means in some cases, 434C libraries for this. AnyEvent will try to do its best, which
435signals will be delayed. The maximum time a signal might be delayed is 435means in some cases, signals will be delayed. The maximum time
436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436a signal might be delayed is 10 seconds by default, but can
437variable can be changed only before the first signal watcher is created, 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
438and should be left alone otherwise. This variable determines how often 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the L<ENVIRONMENT VARIABLES>
439AnyEvent polls for signals (in case a wake-up was missed). Higher values 439section for details.
440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442 440
443All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
444L<Async::Interrupt> module, which works with most event loops. It will not 442L<Async::Interrupt> module, which works with most event loops. It will not
445work with inherently broken event loops such as L<Event> or L<Event::Lib> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
446(and not with L<POE> currently, as POE does its own workaround with 444(and not with L<POE> currently). For those, you just have to suffer the
447one-second latency). For those, you just have to suffer the delays. 445delays.
448 446
449=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
450 448
451 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452 450
482thing in an AnyEvent program, you I<have> to create at least one 480thing in an AnyEvent program, you I<have> to create at least one
483watcher before you C<fork> the child (alternatively, you can call 481watcher before you C<fork> the child (alternatively, you can call
484C<AnyEvent::detect>). 482C<AnyEvent::detect>).
485 483
486As most event loops do not support waiting for child events, they will be 484As most event loops do not support waiting for child events, they will be
487emulated by AnyEvent in most cases, in which the latency and race problems 485emulated by AnyEvent in most cases, in which case the latency and race
488mentioned in the description of signal watchers apply. 486problems mentioned in the description of signal watchers apply.
489 487
490Example: fork a process and wait for it 488Example: fork a process and wait for it
491 489
492 my $done = AnyEvent->condvar; 490 my $done = AnyEvent->condvar;
493 491
765 }; 763 };
766 } 764 }
767 765
768 $cv->end; 766 $cv->end;
769 767
768 ...
769
770 my $results = $cv->recv;
771
770This code fragment supposedly pings a number of hosts and calls 772This code fragment supposedly pings a number of hosts and calls
771C<send> after results for all then have have been gathered - in any 773C<send> after results for all then have have been gathered - in any
772order. To achieve this, the code issues a call to C<begin> when it starts 774order. To achieve this, the code issues a call to C<begin> when it starts
773each ping request and calls C<end> when it has received some result for 775each ping request and calls C<end> when it has received some result for
774it. Since C<begin> and C<end> only maintain a counter, the order in which 776it. Since C<begin> and C<end> only maintain a counter, the order in which
809 811
810In list context, all parameters passed to C<send> will be returned, 812In list context, all parameters passed to C<send> will be returned,
811in scalar context only the first one will be returned. 813in scalar context only the first one will be returned.
812 814
813Note that doing a blocking wait in a callback is not supported by any 815Note that doing a blocking wait in a callback is not supported by any
814event loop, that is, recursive invocation of a blocking C<< ->recv 816event loop, that is, recursive invocation of a blocking C<< ->recv >> is
815>> is not allowed, and the C<recv> call will C<croak> if such a 817not allowed and the C<recv> call will C<croak> if such a condition is
816condition is detected. This condition can be slightly loosened by using 818detected. This requirement can be dropped by relying on L<Coro::AnyEvent>
817L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from 819, which allows you to do a blocking C<< ->recv >> from any thread
818any thread that doesn't run the event loop itself. 820that doesn't run the event loop itself. L<Coro::AnyEvent> is loaded
821automatically when L<Coro> is used with L<AnyEvent>, so code does not need
822to do anything special to take advantage of that: any code that would
823normally block your program because it calls C<recv>, be executed in an
824C<async> thread instead without blocking other threads.
819 825
820Not all event models support a blocking wait - some die in that case 826Not all event models support a blocking wait - some die in that case
821(programs might want to do that to stay interactive), so I<if you are 827(programs might want to do that to stay interactive), so I<if you are
822using this from a module, never require a blocking wait>. Instead, let the 828using this from a module, never require a blocking wait>. Instead, let the
823caller decide whether the call will block or not (for example, by coupling 829caller decide whether the call will block or not (for example, by coupling
860use. If EV is not installed, then AnyEvent will fall back to its own 866use. If EV is not installed, then AnyEvent will fall back to its own
861pure-perl implementation, which is available everywhere as it comes with 867pure-perl implementation, which is available everywhere as it comes with
862AnyEvent itself. 868AnyEvent itself.
863 869
864 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 870 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
865 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 871 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
866 872
867=item Backends that are transparently being picked up when they are used. 873=item Backends that are transparently being picked up when they are used.
868 874
869These will be used if they are already loaded when the first watcher 875These will be used if they are already loaded when the first watcher
870is created, in which case it is assumed that the application is using 876is created, in which case it is assumed that the application is using
876 AnyEvent::Impl::Glib based on Glib, slow but very stable. 882 AnyEvent::Impl::Glib based on Glib, slow but very stable.
877 AnyEvent::Impl::Tk based on Tk, very broken. 883 AnyEvent::Impl::Tk based on Tk, very broken.
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 884 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 885 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 886 AnyEvent::Impl::Irssi used when running within irssi.
887 AnyEvent::Impl::IOAsync based on IO::Async.
888 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
889 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
881 890
882=item Backends with special needs. 891=item Backends with special needs.
883 892
884Qt requires the Qt::Application to be instantiated first, but will 893Qt requires the Qt::Application to be instantiated first, but will
885otherwise be picked up automatically. As long as the main program 894otherwise be picked up automatically. As long as the main program
886instantiates the application before any AnyEvent watchers are created, 895instantiates the application before any AnyEvent watchers are created,
887everything should just work. 896everything should just work.
888 897
889 AnyEvent::Impl::Qt based on Qt. 898 AnyEvent::Impl::Qt based on Qt.
890
891Support for IO::Async can only be partial, as it is too broken and
892architecturally limited to even support the AnyEvent API. It also
893is the only event loop that needs the loop to be set explicitly, so
894it can only be used by a main program knowing about AnyEvent. See
895L<AnyEvent::Impl::IOAsync> for the gory details.
896
897 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
898 899
899=item Event loops that are indirectly supported via other backends. 900=item Event loops that are indirectly supported via other backends.
900 901
901Some event loops can be supported via other modules: 902Some event loops can be supported via other modules:
902 903
938 939
939Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 940Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
940if necessary. You should only call this function right before you would 941if necessary. You should only call this function right before you would
941have created an AnyEvent watcher anyway, that is, as late as possible at 942have created an AnyEvent watcher anyway, that is, as late as possible at
942runtime, and not e.g. during initialisation of your module. 943runtime, and not e.g. during initialisation of your module.
944
945The effect of calling this function is as if a watcher had been created
946(specifically, actions that happen "when the first watcher is created"
947happen when calling detetc as well).
943 948
944If you need to do some initialisation before AnyEvent watchers are 949If you need to do some initialisation before AnyEvent watchers are
945created, use C<post_detect>. 950created, use C<post_detect>.
946 951
947=item $guard = AnyEvent::post_detect { BLOCK } 952=item $guard = AnyEvent::post_detect { BLOCK }
1010 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent 1015 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
1011 # as soon as it is 1016 # as soon as it is
1012 push @AnyEvent::post_detect, sub { require Coro::AnyEvent }; 1017 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
1013 } 1018 }
1014 1019
1020=item AnyEvent::postpone { BLOCK }
1021
1022Arranges for the block to be executed as soon as possible, but not before
1023the call itself returns. In practise, the block will be executed just
1024before the event loop polls for new events, or shortly afterwards.
1025
1026This function never returns anything (to make the C<return postpone { ...
1027}> idiom more useful.
1028
1029To understand the usefulness of this function, consider a function that
1030asynchronously does something for you and returns some transaction
1031object or guard to let you cancel the operation. For example,
1032C<AnyEvent::Socket::tcp_connect>:
1033
1034 # start a conenction attempt unless one is active
1035 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
1036 delete $self->{connect_guard};
1037 ...
1038 };
1039
1040Imagine that this function could instantly call the callback, for
1041example, because it detects an obvious error such as a negative port
1042number. Invoking the callback before the function returns causes problems
1043however: the callback will be called and will try to delete the guard
1044object. But since the function hasn't returned yet, there is nothing to
1045delete. When the function eventually returns it will assign the guard
1046object to C<< $self->{connect_guard} >>, where it will likely never be
1047deleted, so the program thinks it is still trying to connect.
1048
1049This is where C<AnyEvent::postpone> should be used. Instead of calling the
1050callback directly on error:
1051
1052 $cb->(undef), return # signal error to callback, BAD!
1053 if $some_error_condition;
1054
1055It should use C<postpone>:
1056
1057 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1058 if $some_error_condition;
1059
1060=item AnyEvent::log $level, $msg[, @args]
1061
1062Log the given C<$msg> at the given C<$level>.
1063
1064If L<AnyEvent::Log> is not loaded then this function makes a simple test
1065to see whether the message will be logged. If the test succeeds it will
1066load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1067the L<AnyEvent::Log> documentation for details.
1068
1069If the test fails it will simply return. Right now this happens when a
1070numerical loglevel is used and it is larger than the level specified via
1071C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1072
1073If you want to sprinkle loads of logging calls around your code, consider
1074creating a logger callback with the C<AnyEvent::Log::logger> function,
1075which can reduce typing, codesize and can reduce the logging overhead
1076enourmously.
1077
1015=back 1078=back
1016 1079
1017=head1 WHAT TO DO IN A MODULE 1080=head1 WHAT TO DO IN A MODULE
1018 1081
1019As a module author, you should C<use AnyEvent> and call AnyEvent methods 1082As a module author, you should C<use AnyEvent> and call AnyEvent methods
1052modules might create watchers when they are loaded, and AnyEvent will 1115modules might create watchers when they are loaded, and AnyEvent will
1053decide on the event model to use as soon as it creates watchers, and it 1116decide on the event model to use as soon as it creates watchers, and it
1054might choose the wrong one unless you load the correct one yourself. 1117might choose the wrong one unless you load the correct one yourself.
1055 1118
1056You can chose to use a pure-perl implementation by loading the 1119You can chose to use a pure-perl implementation by loading the
1057C<AnyEvent::Impl::Perl> module, which gives you similar behaviour 1120C<AnyEvent::Loop> module, which gives you similar behaviour
1058everywhere, but letting AnyEvent chose the model is generally better. 1121everywhere, but letting AnyEvent chose the model is generally better.
1059 1122
1060=head2 MAINLOOP EMULATION 1123=head2 MAINLOOP EMULATION
1061 1124
1062Sometimes (often for short test scripts, or even standalone programs who 1125Sometimes (often for short test scripts, or even standalone programs who
1075 1138
1076 1139
1077=head1 OTHER MODULES 1140=head1 OTHER MODULES
1078 1141
1079The following is a non-exhaustive list of additional modules that use 1142The following is a non-exhaustive list of additional modules that use
1080AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1143AnyEvent as a client and can therefore be mixed easily with other
1081modules and other event loops in the same program. Some of the modules 1144AnyEvent modules and other event loops in the same program. Some of the
1082come as part of AnyEvent, the others are available via CPAN. 1145modules come as part of AnyEvent, the others are available via CPAN (see
1146L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1147a longer non-exhaustive list), and the list is heavily biased towards
1148modules of the AnyEvent author himself :)
1083 1149
1084=over 4 1150=over 4
1085 1151
1086=item L<AnyEvent::Util> 1152=item L<AnyEvent::Util>
1087 1153
1107=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1173=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1108 1174
1109Implement event-based interfaces to the protocols of the same name (for 1175Implement event-based interfaces to the protocols of the same name (for
1110the curious, IGS is the International Go Server and FCP is the Freenet 1176the curious, IGS is the International Go Server and FCP is the Freenet
1111Client Protocol). 1177Client Protocol).
1112
1113=item L<AnyEvent::Handle::UDP>
1114
1115Here be danger!
1116
1117As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1118there are so many things wrong with AnyEvent::Handle::UDP, most notably
1119its use of a stream-based API with a protocol that isn't streamable, that
1120the only way to improve it is to delete it.
1121
1122It features data corruption (but typically only under load) and general
1123confusion. On top, the author is not only clueless about UDP but also
1124fact-resistant - some gems of his understanding: "connect doesn't work
1125with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1126packets", "I don't need to implement proper error checking as UDP doesn't
1127support error checking" and so on - he doesn't even understand what's
1128wrong with his module when it is explained to him.
1129
1130=item L<AnyEvent::DBI>
1131
1132Executes L<DBI> requests asynchronously in a proxy process for you,
1133notifying you in an event-based way when the operation is finished.
1134 1178
1135=item L<AnyEvent::AIO> 1179=item L<AnyEvent::AIO>
1136 1180
1137Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1181Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1138toolbox of every event programmer. AnyEvent::AIO transparently fuses 1182toolbox of every event programmer. AnyEvent::AIO transparently fuses
1139L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1183L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1140file I/O, and much more. 1184file I/O, and much more.
1141 1185
1186=item L<AnyEvent::Filesys::Notify>
1187
1188AnyEvent is good for non-blocking stuff, but it can't detect file or
1189path changes (e.g. "watch this directory for new files", "watch this
1190file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1191do just that in a portbale fashion, supporting inotify on GNU/Linux and
1192some weird, without doubt broken, stuff on OS X to monitor files. It can
1193fall back to blocking scans at regular intervals transparently on other
1194platforms, so it's about as portable as it gets.
1195
1196(I haven't used it myself, but I haven't heard anybody complaining about
1197it yet).
1198
1199=item L<AnyEvent::DBI>
1200
1201Executes L<DBI> requests asynchronously in a proxy process for you,
1202notifying you in an event-based way when the operation is finished.
1203
1142=item L<AnyEvent::HTTPD> 1204=item L<AnyEvent::HTTPD>
1143 1205
1144A simple embedded webserver. 1206A simple embedded webserver.
1145 1207
1146=item L<AnyEvent::FastPing> 1208=item L<AnyEvent::FastPing>
1147 1209
1148The fastest ping in the west. 1210The fastest ping in the west.
1149 1211
1150=item L<Coro> 1212=item L<Coro>
1151 1213
1152Has special support for AnyEvent via L<Coro::AnyEvent>. 1214Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1215to simply invert the flow control - don't call us, we will call you:
1216
1217 async {
1218 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1219 print "5 seconds later!\n";
1220
1221 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1222 my $line = <STDIN>; # works for ttys
1223
1224 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1225 my ($body, $hdr) = Coro::rouse_wait;
1226 };
1153 1227
1154=back 1228=back
1155 1229
1156=cut 1230=cut
1157 1231
1158package AnyEvent; 1232package AnyEvent;
1159 1233
1160# basically a tuned-down version of common::sense 1234# basically a tuned-down version of common::sense
1161sub common_sense { 1235sub common_sense {
1162 # from common:.sense 1.0 1236 # from common:.sense 3.5
1237 local $^W;
1163 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00"; 1238 ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
1164 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl) 1239 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1165 $^H |= 0x00000600; 1240 $^H |= 0x00000600;
1166} 1241}
1167 1242
1168BEGIN { AnyEvent::common_sense } 1243BEGIN { AnyEvent::common_sense }
1169 1244
1170use Carp (); 1245use Carp ();
1171 1246
1172our $VERSION = '5.271'; 1247our $VERSION = '7.04';
1173our $MODEL; 1248our $MODEL;
1174
1175our $AUTOLOAD;
1176our @ISA; 1249our @ISA;
1177
1178our @REGISTRY; 1250our @REGISTRY;
1179
1180our $VERBOSE; 1251our $VERBOSE;
1252our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1253our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1181 1254
1182BEGIN { 1255BEGIN {
1183 require "AnyEvent/constants.pl"; 1256 require "AnyEvent/constants.pl";
1184 1257
1185 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1258 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1186 1259
1187 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1260 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1188 if ${^TAINT}; 1261 if ${^TAINT};
1189 1262
1190 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1263 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1264 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1191 1265
1192} 1266 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1267 if ${^TAINT};
1193 1268
1194our $MAX_SIGNAL_LATENCY = 10; 1269 # $ENV{PERL_ANYEVENT_xxx} now valid
1195 1270
1196our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1271 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1197 1272
1198{
1199 my $idx; 1273 my $idx;
1200 $PROTOCOL{$_} = ++$idx 1274 $PROTOCOL{$_} = ++$idx
1201 for reverse split /\s*,\s*/, 1275 for reverse split /\s*,\s*/,
1202 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1276 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1203} 1277}
1204 1278
1279our @post_detect;
1280
1281sub post_detect(&) {
1282 my ($cb) = @_;
1283
1284 push @post_detect, $cb;
1285
1286 defined wantarray
1287 ? bless \$cb, "AnyEvent::Util::postdetect"
1288 : ()
1289}
1290
1291sub AnyEvent::Util::postdetect::DESTROY {
1292 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1293}
1294
1295our $POSTPONE_W;
1296our @POSTPONE;
1297
1298sub _postpone_exec {
1299 undef $POSTPONE_W;
1300
1301 &{ shift @POSTPONE }
1302 while @POSTPONE;
1303}
1304
1305sub postpone(&) {
1306 push @POSTPONE, shift;
1307
1308 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1309
1310 ()
1311}
1312
1313sub log($$;@) {
1314 # only load the big bloated module when we actually are about to log something
1315 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1316 local ($!, $@);
1317 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1318 # AnyEvent::Log overwrites this function
1319 goto &log;
1320 }
1321
1322 0 # not logged
1323}
1324
1325sub _logger($;$) {
1326 my ($level, $renabled) = @_;
1327
1328 $$renabled = $level <= $VERBOSE;
1329
1330 my $logger = [(caller)[0], $level, $renabled];
1331
1332 $AnyEvent::Log::LOGGER{$logger+0} = $logger;
1333
1334# return unless defined wantarray;
1335#
1336# require AnyEvent::Util;
1337# my $guard = AnyEvent::Util::guard (sub {
1338# # "clean up"
1339# delete $LOGGER{$logger+0};
1340# });
1341#
1342# sub {
1343# return 0 unless $$renabled;
1344#
1345# $guard if 0; # keep guard alive, but don't cause runtime overhead
1346# require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1347# package AnyEvent::Log;
1348# _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1349# }
1350}
1351
1352if (length $ENV{PERL_ANYEVENT_LOG}) {
1353 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1354}
1355
1205my @models = ( 1356our @models = (
1206 [EV:: => AnyEvent::Impl::EV:: , 1], 1357 [EV:: => AnyEvent::Impl::EV::],
1207 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], 1358 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1208 # everything below here will not (normally) be autoprobed 1359 # everything below here will not (normally) be autoprobed
1209 # as the pureperl backend should work everywhere 1360 # as the pure perl backend should work everywhere
1210 # and is usually faster 1361 # and is usually faster
1362 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1211 [Event:: => AnyEvent::Impl::Event::, 1], 1363 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1212 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1364 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1365 # everything below here should not be autoloaded
1213 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1366 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1214 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1215 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1367 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1216 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1368 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1217 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1369 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1218 [Wx:: => AnyEvent::Impl::POE::], 1370 [Wx:: => AnyEvent::Impl::POE::],
1219 [Prima:: => AnyEvent::Impl::POE::], 1371 [Prima:: => AnyEvent::Impl::POE::],
1220 # IO::Async is just too broken - we would need workarounds for its 1372 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1221 # byzantine signal and broken child handling, among others. 1373 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1222 # IO::Async is rather hard to detect, as it doesn't have any 1374 [FLTK:: => AnyEvent::Impl::FLTK::],
1223 # obvious default class.
1224 [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1225 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1226 [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1227 [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program
1228); 1375);
1229 1376
1230our %method = map +($_ => 1), 1377our @isa_hook;
1378
1379sub _isa_set {
1380 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1381
1382 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1383 for 1 .. $#pkg;
1384
1385 grep $_ && $_->[1], @isa_hook
1386 and AE::_reset ();
1387}
1388
1389# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1390sub _isa_hook($$;$) {
1391 my ($i, $pkg, $reset_ae) = @_;
1392
1393 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1394
1395 _isa_set;
1396}
1397
1398# all autoloaded methods reserve the complete glob, not just the method slot.
1399# due to bugs in perls method cache implementation.
1231 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1400our @methods = qw(io timer time now now_update signal child idle condvar);
1232
1233our @post_detect;
1234
1235sub post_detect(&) {
1236 my ($cb) = @_;
1237
1238 push @post_detect, $cb;
1239
1240 defined wantarray
1241 ? bless \$cb, "AnyEvent::Util::postdetect"
1242 : ()
1243}
1244
1245sub AnyEvent::Util::postdetect::DESTROY {
1246 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1247}
1248 1401
1249sub detect() { 1402sub detect() {
1403 return $MODEL if $MODEL; # some programs keep references to detect
1404
1405 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1406 # the author knows about the problems and what it does to AnyEvent as a whole
1407 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1408 # anyway.
1409 AnyEvent::log fatal => "IO::Async::Loop::AnyEvent detected - that module is broken by\n"
1410 . "design, abuses internals and breaks AnyEvent - will not continue."
1411 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1412
1413 local $!; # for good measure
1414 local $SIG{__DIE__}; # we use eval
1415
1250 # free some memory 1416 # free some memory
1251 *detect = sub () { $MODEL }; 1417 *detect = sub () { $MODEL };
1418 # undef &func doesn't correctly update the method cache. grmbl.
1419 # so we delete the whole glob. grmbl.
1420 # otoh, perl doesn't let me undef an active usb, but it lets me free
1421 # a glob with an active sub. hrm. i hope it works, but perl is
1422 # usually buggy in this department. sigh.
1423 delete @{"AnyEvent::"}{@methods};
1424 undef @methods;
1252 1425
1253 local $!; # for good measure
1254 local $SIG{__DIE__};
1255
1256 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1426 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1257 my $model = "AnyEvent::Impl::$1"; 1427 my $model = $1;
1428 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1258 if (eval "require $model") { 1429 if (eval "require $model") {
1430 AnyEvent::log 7 => "Loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1259 $MODEL = $model; 1431 $MODEL = $model;
1260 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1261 } else { 1432 } else {
1262 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1433 AnyEvent::log 4 => "Unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1263 } 1434 }
1264 } 1435 }
1265 1436
1266 # check for already loaded models 1437 # check for already loaded models
1267 unless ($MODEL) { 1438 unless ($MODEL) {
1268 for (@REGISTRY, @models) { 1439 for (@REGISTRY, @models) {
1269 my ($package, $model) = @$_; 1440 my ($package, $model) = @$_;
1270 if (${"$package\::VERSION"} > 0) { 1441 if (${"$package\::VERSION"} > 0) {
1271 if (eval "require $model") { 1442 if (eval "require $model") {
1443 AnyEvent::log 7 => "Autodetected model '$model', using it.";
1272 $MODEL = $model; 1444 $MODEL = $model;
1273 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2; 1445 last;
1446 } else {
1447 AnyEvent::log 8 => "Detected event loop $package, but cannot load '$model', skipping: $@";
1448 }
1449 }
1450 }
1451
1452 unless ($MODEL) {
1453 # try to autoload a model
1454 for (@REGISTRY, @models) {
1455 my ($package, $model) = @$_;
1456 if (
1457 eval "require $package"
1458 and ${"$package\::VERSION"} > 0
1459 and eval "require $model"
1460 ) {
1461 AnyEvent::log 7 => "Autoloaded model '$model', using it.";
1462 $MODEL = $model;
1274 last; 1463 last;
1275 } 1464 }
1276 } 1465 }
1277 }
1278
1279 unless ($MODEL) {
1280 # try to autoload a model
1281 for (@REGISTRY, @models) {
1282 my ($package, $model, $autoload) = @$_;
1283 if (
1284 $autoload
1285 and eval "require $package"
1286 and ${"$package\::VERSION"} > 0
1287 and eval "require $model"
1288 ) {
1289 $MODEL = $model;
1290 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1291 last;
1292 }
1293 }
1294 1466
1295 $MODEL 1467 $MODEL
1296 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n"; 1468 or AnyEvent::log fatal => "Backend autodetection failed - did you properly install AnyEvent?";
1297 } 1469 }
1298 } 1470 }
1299 1471
1300 @models = (); # free probe data 1472 # free memory only needed for probing
1473 undef @models;
1474 undef @REGISTRY;
1301 1475
1302 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1476 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1303 unshift @ISA, $MODEL;
1304 1477
1305 # now nuke some methods that are overriden by the backend. 1478 # now nuke some methods that are overridden by the backend.
1306 # SUPER is not allowed. 1479 # SUPER usage is not allowed in these.
1307 for (qw(time signal child idle)) { 1480 for (qw(time signal child idle)) {
1308 undef &{"AnyEvent::Base::$_"} 1481 undef &{"AnyEvent::Base::$_"}
1309 if defined &{"$MODEL\::$_"}; 1482 if defined &{"$MODEL\::$_"};
1310 } 1483 }
1311 1484
1312 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT}; 1485 _isa_set;
1486
1487 # we're officially open!
1488
1489 if ($ENV{PERL_ANYEVENT_STRICT}) {
1490 require AnyEvent::Strict;
1491 }
1492
1493 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1494 require AnyEvent::Debug;
1495 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1496 }
1497
1498 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1499 require AnyEvent::Socket;
1500 require AnyEvent::Debug;
1501
1502 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1503 $shell =~ s/\$\$/$$/g;
1504
1505 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1506 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1507 }
1508
1509 # now the anyevent environment is set up as the user told us to, so
1510 # call the actual user code - post detects
1313 1511
1314 (shift @post_detect)->() while @post_detect; 1512 (shift @post_detect)->() while @post_detect;
1513 undef @post_detect;
1315 1514
1316 *post_detect = sub(&) { 1515 *post_detect = sub(&) {
1317 shift->(); 1516 shift->();
1318 1517
1319 undef 1518 undef
1320 }; 1519 };
1321 1520
1322 $MODEL 1521 $MODEL
1323} 1522}
1324 1523
1325sub AUTOLOAD { 1524for my $name (@methods) {
1326 (my $func = $AUTOLOAD) =~ s/.*://; 1525 *$name = sub {
1327
1328 $method{$func}
1329 or Carp::croak "$func: not a valid AnyEvent class method";
1330
1331 detect; 1526 detect;
1332 1527 # we use goto because
1333 my $class = shift; 1528 # a) it makes the thunk more transparent
1334 $class->$func (@_); 1529 # b) it allows us to delete the thunk later
1530 goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
1531 };
1335} 1532}
1336 1533
1337# utility function to dup a filehandle. this is used by many backends 1534# utility function to dup a filehandle. this is used by many backends
1338# to support binding more than one watcher per filehandle (they usually 1535# to support binding more than one watcher per filehandle (they usually
1339# allow only one watcher per fd, so we dup it to get a different one). 1536# allow only one watcher per fd, so we dup it to get a different one).
1363 1560
1364package AE; 1561package AE;
1365 1562
1366our $VERSION = $AnyEvent::VERSION; 1563our $VERSION = $AnyEvent::VERSION;
1367 1564
1565sub _reset() {
1566 eval q{
1368# fall back to the main API by default - backends and AnyEvent::Base 1567 # fall back to the main API by default - backends and AnyEvent::Base
1369# implementations can overwrite these. 1568 # implementations can overwrite these.
1370 1569
1371sub io($$$) { 1570 sub io($$$) {
1372 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) 1571 AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
1373} 1572 }
1374 1573
1375sub timer($$$) { 1574 sub timer($$$) {
1376 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]) 1575 AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
1377} 1576 }
1378 1577
1379sub signal($$) { 1578 sub signal($$) {
1380 AnyEvent->signal (signal => $_[0], cb => $_[1]) 1579 AnyEvent->signal (signal => $_[0], cb => $_[1])
1381} 1580 }
1382 1581
1383sub child($$) { 1582 sub child($$) {
1384 AnyEvent->child (pid => $_[0], cb => $_[1]) 1583 AnyEvent->child (pid => $_[0], cb => $_[1])
1385} 1584 }
1386 1585
1387sub idle($) { 1586 sub idle($) {
1388 AnyEvent->idle (cb => $_[0]) 1587 AnyEvent->idle (cb => $_[0]);
1389} 1588 }
1390 1589
1391sub cv(;&) { 1590 sub cv(;&) {
1392 AnyEvent->condvar (@_ ? (cb => $_[0]) : ()) 1591 AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
1393} 1592 }
1394 1593
1395sub now() { 1594 sub now() {
1396 AnyEvent->now 1595 AnyEvent->now
1397} 1596 }
1398 1597
1399sub now_update() { 1598 sub now_update() {
1400 AnyEvent->now_update 1599 AnyEvent->now_update
1401} 1600 }
1402 1601
1403sub time() { 1602 sub time() {
1404 AnyEvent->time 1603 AnyEvent->time
1604 }
1605
1606 *postpone = \&AnyEvent::postpone;
1607 *log = \&AnyEvent::log;
1608 };
1609 die if $@;
1405} 1610}
1611
1612BEGIN { _reset }
1406 1613
1407package AnyEvent::Base; 1614package AnyEvent::Base;
1408 1615
1409# default implementations for many methods 1616# default implementations for many methods
1410 1617
1411sub time { 1618sub time {
1412 eval q{ # poor man's autoloading {} 1619 eval q{ # poor man's autoloading {}
1413 # probe for availability of Time::HiRes 1620 # probe for availability of Time::HiRes
1414 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1621 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1415 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1622 *time = sub { Time::HiRes::time () };
1416 *AE::time = \&Time::HiRes::time; 1623 *AE::time = \& Time::HiRes::time ;
1624 *now = \&time;
1625 AnyEvent::log 8 => "using Time::HiRes for sub-second timing accuracy.";
1417 # if (eval "use POSIX (); (POSIX::times())... 1626 # if (eval "use POSIX (); (POSIX::times())...
1418 } else { 1627 } else {
1419 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1628 *time = sub { CORE::time };
1420 *AE::time = sub (){ time }; # epic fail 1629 *AE::time = sub (){ CORE::time };
1630 *now = \&time;
1631 AnyEvent::log 3 => "Using built-in time(), no sub-second resolution!";
1421 } 1632 }
1422
1423 *time = sub { AE::time }; # different prototypes
1424 }; 1633 };
1425 die if $@; 1634 die if $@;
1426 1635
1427 &time 1636 &time
1428} 1637}
1429 1638
1430*now = \&time; 1639*now = \&time;
1431
1432sub now_update { } 1640sub now_update { }
1433 1641
1642sub _poll {
1643 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1644}
1645
1434# default implementation for ->condvar 1646# default implementation for ->condvar
1647# in fact, the default should not be overwritten
1435 1648
1436sub condvar { 1649sub condvar {
1437 eval q{ # poor man's autoloading {} 1650 eval q{ # poor man's autoloading {}
1438 *condvar = sub { 1651 *condvar = sub {
1439 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1652 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1517 1730
1518sub signal { 1731sub signal {
1519 eval q{ # poor man's autoloading {} 1732 eval q{ # poor man's autoloading {}
1520 # probe for availability of Async::Interrupt 1733 # probe for availability of Async::Interrupt
1521 if (_have_async_interrupt) { 1734 if (_have_async_interrupt) {
1522 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1735 AnyEvent::log 8 => "Using Async::Interrupt for race-free signal handling.";
1523 1736
1524 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1737 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1525 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1738 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1526 1739
1527 } else { 1740 } else {
1528 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1741 AnyEvent::log 8 => "Using emulated perl signal handling with latency timer.";
1529 1742
1530 if (AnyEvent::WIN32) { 1743 if (AnyEvent::WIN32) {
1531 require AnyEvent::Util; 1744 require AnyEvent::Util;
1532 1745
1533 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1746 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
1609 : sysread $SIGPIPE_R, (my $dummy), 9; 1822 : sysread $SIGPIPE_R, (my $dummy), 9;
1610 1823
1611 while (%SIG_EV) { 1824 while (%SIG_EV) {
1612 for (keys %SIG_EV) { 1825 for (keys %SIG_EV) {
1613 delete $SIG_EV{$_}; 1826 delete $SIG_EV{$_};
1614 $_->() for values %{ $SIG_CB{$_} || {} }; 1827 &$_ for values %{ $SIG_CB{$_} || {} };
1615 } 1828 }
1616 } 1829 }
1617 }; 1830 };
1618 }; 1831 };
1619 die if $@; 1832 die if $@;
1624# default implementation for ->child 1837# default implementation for ->child
1625 1838
1626our %PID_CB; 1839our %PID_CB;
1627our $CHLD_W; 1840our $CHLD_W;
1628our $CHLD_DELAY_W; 1841our $CHLD_DELAY_W;
1629our $WNOHANG;
1630 1842
1631# used by many Impl's 1843# used by many Impl's
1632sub _emit_childstatus($$) { 1844sub _emit_childstatus($$) {
1633 my (undef, $rpid, $rstatus) = @_; 1845 my (undef, $rpid, $rstatus) = @_;
1634 1846
1641 eval q{ # poor man's autoloading {} 1853 eval q{ # poor man's autoloading {}
1642 *_sigchld = sub { 1854 *_sigchld = sub {
1643 my $pid; 1855 my $pid;
1644 1856
1645 AnyEvent->_emit_childstatus ($pid, $?) 1857 AnyEvent->_emit_childstatus ($pid, $?)
1646 while ($pid = waitpid -1, $WNOHANG) > 0; 1858 while ($pid = waitpid -1, WNOHANG) > 0;
1647 }; 1859 };
1648 1860
1649 *child = sub { 1861 *child = sub {
1650 my (undef, %arg) = @_; 1862 my (undef, %arg) = @_;
1651 1863
1652 defined (my $pid = $arg{pid} + 0) 1864 my $pid = $arg{pid};
1653 or Carp::croak "required option 'pid' is missing"; 1865 my $cb = $arg{cb};
1654 1866
1655 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1867 $PID_CB{$pid}{$cb+0} = $cb;
1656
1657 # WNOHANG is almost cetrainly 1 everywhere
1658 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1659 ? 1
1660 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1661 1868
1662 unless ($CHLD_W) { 1869 unless ($CHLD_W) {
1663 $CHLD_W = AE::signal CHLD => \&_sigchld; 1870 $CHLD_W = AE::signal CHLD => \&_sigchld;
1664 # child could be a zombie already, so make at least one round 1871 # child could be a zombie already, so make at least one round
1665 &_sigchld; 1872 &_sigchld;
1666 } 1873 }
1667 1874
1668 bless [$pid, $arg{cb}], "AnyEvent::Base::child" 1875 bless [$pid, $cb+0], "AnyEvent::Base::child"
1669 }; 1876 };
1670 1877
1671 *AnyEvent::Base::child::DESTROY = sub { 1878 *AnyEvent::Base::child::DESTROY = sub {
1672 my ($pid, $cb) = @{$_[0]}; 1879 my ($pid, $icb) = @{$_[0]};
1673 1880
1674 delete $PID_CB{$pid}{$cb}; 1881 delete $PID_CB{$pid}{$icb};
1675 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1882 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1676 1883
1677 undef $CHLD_W unless keys %PID_CB; 1884 undef $CHLD_W unless keys %PID_CB;
1678 }; 1885 };
1679 }; 1886 };
1692 1899
1693 my ($cb, $w, $rcb) = $arg{cb}; 1900 my ($cb, $w, $rcb) = $arg{cb};
1694 1901
1695 $rcb = sub { 1902 $rcb = sub {
1696 if ($cb) { 1903 if ($cb) {
1697 $w = _time; 1904 $w = AE::time;
1698 &$cb; 1905 &$cb;
1699 $w = _time - $w; 1906 $w = AE::time - $w;
1700 1907
1701 # never use more then 50% of the time for the idle watcher, 1908 # never use more then 50% of the time for the idle watcher,
1702 # within some limits 1909 # within some limits
1703 $w = 0.0001 if $w < 0.0001; 1910 $w = 0.0001 if $w < 0.0001;
1704 $w = 5 if $w > 5; 1911 $w = 5 if $w > 5;
1727 1934
1728package AnyEvent::CondVar; 1935package AnyEvent::CondVar;
1729 1936
1730our @ISA = AnyEvent::CondVar::Base::; 1937our @ISA = AnyEvent::CondVar::Base::;
1731 1938
1939# only to be used for subclassing
1940sub new {
1941 my $class = shift;
1942 bless AnyEvent->condvar (@_), $class
1943}
1944
1732package AnyEvent::CondVar::Base; 1945package AnyEvent::CondVar::Base;
1733 1946
1734#use overload 1947#use overload
1735# '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1948# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1736# fallback => 1; 1949# fallback => 1;
1745 1958
1746sub _send { 1959sub _send {
1747 # nop 1960 # nop
1748} 1961}
1749 1962
1963sub _wait {
1964 AnyEvent->_poll until $_[0]{_ae_sent};
1965}
1966
1750sub send { 1967sub send {
1751 my $cv = shift; 1968 my $cv = shift;
1752 $cv->{_ae_sent} = [@_]; 1969 $cv->{_ae_sent} = [@_];
1753 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb}; 1970 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
1754 $cv->_send; 1971 $cv->_send;
1761 1978
1762sub ready { 1979sub ready {
1763 $_[0]{_ae_sent} 1980 $_[0]{_ae_sent}
1764} 1981}
1765 1982
1766sub _wait {
1767 $WAITING
1768 and !$_[0]{_ae_sent}
1769 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1770
1771 local $WAITING = 1;
1772 AnyEvent->one_event while !$_[0]{_ae_sent};
1773}
1774
1775sub recv { 1983sub recv {
1984 unless ($_[0]{_ae_sent}) {
1985 $WAITING
1986 and Carp::croak "AnyEvent::CondVar: recursive blocking wait attempted";
1987
1988 local $WAITING = 1;
1776 $_[0]->_wait; 1989 $_[0]->_wait;
1990 }
1777 1991
1778 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1992 $_[0]{_ae_croak}
1779 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1993 and Carp::croak $_[0]{_ae_croak};
1994
1995 wantarray
1996 ? @{ $_[0]{_ae_sent} }
1997 : $_[0]{_ae_sent}[0]
1780} 1998}
1781 1999
1782sub cb { 2000sub cb {
1783 my $cv = shift; 2001 my $cv = shift;
1784 2002
1800 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } }; 2018 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
1801} 2019}
1802 2020
1803# undocumented/compatibility with pre-3.4 2021# undocumented/compatibility with pre-3.4
1804*broadcast = \&send; 2022*broadcast = \&send;
1805*wait = \&_wait; 2023*wait = \&recv;
1806 2024
1807=head1 ERROR AND EXCEPTION HANDLING 2025=head1 ERROR AND EXCEPTION HANDLING
1808 2026
1809In general, AnyEvent does not do any error handling - it relies on the 2027In general, AnyEvent does not do any error handling - it relies on the
1810caller to do that if required. The L<AnyEvent::Strict> module (see also 2028caller to do that if required. The L<AnyEvent::Strict> module (see also
1822$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2040$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1823so on. 2041so on.
1824 2042
1825=head1 ENVIRONMENT VARIABLES 2043=head1 ENVIRONMENT VARIABLES
1826 2044
1827The following environment variables are used by this module or its 2045AnyEvent supports a number of environment variables that tune the
1828submodules. 2046runtime behaviour. They are usually evaluated when AnyEvent is
2047loaded, initialised, or a submodule that uses them is loaded. Many of
2048them also cause AnyEvent to load additional modules - for example,
2049C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2050loaded.
1829 2051
1830Note that AnyEvent will remove I<all> environment variables starting with 2052All the environment variables documented here start with
1831C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2053C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1832enabled. 2054namespace. Other modules are encouraged (but by no means required) to use
2055C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2056namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2057be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2058variables starting with C<AE_>, see below).
2059
2060All variables can also be set via the C<AE_> prefix, that is, instead
2061of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2062case there is a clash btween anyevent and another program that uses
2063C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2064variable to the empty string, as those variables take precedence.
2065
2066When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2067to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2068exists. If taint mode is on, then AnyEvent will remove I<all> environment
2069variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2070with C<undef> or the empty string, if the corresaponding C<AE_> variable
2071is set).
2072
2073The exact algorithm is currently:
2074
2075 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2076 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2077 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2078
2079This ensures that child processes will not see the C<AE_> variables.
2080
2081The following environment variables are currently known to AnyEvent:
1833 2082
1834=over 4 2083=over 4
1835 2084
1836=item C<PERL_ANYEVENT_VERBOSE> 2085=item C<PERL_ANYEVENT_VERBOSE>
1837 2086
1838By default, AnyEvent will be completely silent except in fatal 2087By default, AnyEvent will log messages with loglevel C<4> (C<error>) or
1839conditions. You can set this environment variable to make AnyEvent more 2088higher (see L<AnyEvent::Log>). You can set this environment variable to a
1840talkative. 2089numerical loglevel to make AnyEvent more (or less) talkative.
1841 2090
2091If you want to do more than just set the global logging level
2092you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2093complex specifications.
2094
2095When set to C<0> (C<off>), then no messages whatsoever will be logged with
2096everything else at defaults.
2097
1842When set to C<1> or higher, causes AnyEvent to warn about unexpected 2098When set to C<5> or higher (C<warn>), AnyEvent warns about unexpected
1843conditions, such as not being able to load the event model specified by 2099conditions, such as not being able to load the event model specified by
1844C<PERL_ANYEVENT_MODEL>. 2100C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2101is the minimum recommended level for use during development.
1845 2102
1846When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2103When set to C<7> or higher (info), AnyEvent reports which event model it
1847model it chooses. 2104chooses.
1848 2105
1849When set to C<8> or higher, then AnyEvent will report extra information on 2106When set to C<8> or higher (debug), then AnyEvent will report extra
1850which optional modules it loads and how it implements certain features. 2107information on which optional modules it loads and how it implements
2108certain features.
2109
2110=item C<PERL_ANYEVENT_LOG>
2111
2112Accepts rather complex logging specifications. For example, you could log
2113all C<debug> messages of some module to stderr, warnings and above to
2114stderr, and errors and above to syslog, with:
2115
2116 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2117
2118For the rather extensive details, see L<AnyEvent::Log>.
2119
2120This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2121so will take effect even before AnyEvent has initialised itself.
2122
2123Note that specifying this environment variable causes the L<AnyEvent::Log>
2124module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2125using the latter saves a few hundred kB of memory unless a module
2126explicitly needs the extra features of AnyEvent::Log.
1851 2127
1852=item C<PERL_ANYEVENT_STRICT> 2128=item C<PERL_ANYEVENT_STRICT>
1853 2129
1854AnyEvent does not do much argument checking by default, as thorough 2130AnyEvent does not do much argument checking by default, as thorough
1855argument checking is very costly. Setting this variable to a true value 2131argument checking is very costly. Setting this variable to a true value
1862Unlike C<use strict> (or its modern cousin, C<< use L<common::sense> 2138Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
1863>>, it is definitely recommended to keep it off in production. Keeping 2139>>, it is definitely recommended to keep it off in production. Keeping
1864C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2140C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1865can be very useful, however. 2141can be very useful, however.
1866 2142
2143=item C<PERL_ANYEVENT_DEBUG_SHELL>
2144
2145If this env variable is nonempty, then its contents will be interpreted by
2146C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2147replacing every occurance of C<$$> by the process pid). The shell object
2148is saved in C<$AnyEvent::Debug::SHELL>.
2149
2150This happens when the first watcher is created.
2151
2152For example, to bind a debug shell on a unix domain socket in
2153F<< /tmp/debug<pid>.sock >>, you could use this:
2154
2155 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2156 # connect with e.g.: socat readline /tmp/debug123.sock
2157
2158Or to bind to tcp port 4545 on localhost:
2159
2160 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2161 # connect with e.g.: telnet localhost 4545
2162
2163Note that creating sockets in F</tmp> or on localhost is very unsafe on
2164multiuser systems.
2165
2166=item C<PERL_ANYEVENT_DEBUG_WRAP>
2167
2168Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2169debugging purposes. See C<AnyEvent::Debug::wrap> for details.
2170
1867=item C<PERL_ANYEVENT_MODEL> 2171=item C<PERL_ANYEVENT_MODEL>
1868 2172
1869This can be used to specify the event model to be used by AnyEvent, before 2173This can be used to specify the event model to be used by AnyEvent, before
1870auto detection and -probing kicks in. It must be a string consisting 2174auto detection and -probing kicks in.
1871entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 2175
2176It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
2177or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
1872and the resulting module name is loaded and if the load was successful, 2178resulting module name is loaded and - if the load was successful - used as
1873used as event model. If it fails to load AnyEvent will proceed with 2179event model backend. If it fails to load then AnyEvent will proceed with
1874auto detection and -probing. 2180auto detection and -probing.
1875 2181
1876This functionality might change in future versions. 2182If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
2183nothing gets prepended and the module name is used as-is (hint: C<::> at
2184the end of a string designates a module name and quotes it appropriately).
1877 2185
1878For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 2186For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
1879could start your program like this: 2187could start your program like this:
1880 2188
1881 PERL_ANYEVENT_MODEL=Perl perl ... 2189 PERL_ANYEVENT_MODEL=Perl perl ...
2190
2191=item C<PERL_ANYEVENT_IO_MODEL>
2192
2193The current file I/O model - see L<AnyEvent::IO> for more info.
2194
2195At the moment, only C<Perl> (small, pure-perl, synchronous) and
2196C<IOAIO> (truly asynchronous) are supported. The default is C<IOAIO> if
2197L<AnyEvent::AIO> can be loaded, otherwise it is C<Perl>.
1882 2198
1883=item C<PERL_ANYEVENT_PROTOCOLS> 2199=item C<PERL_ANYEVENT_PROTOCOLS>
1884 2200
1885Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 2201Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1886for IPv4 or IPv6. The default is unspecified (and might change, or be the result 2202for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1899but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2215but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1900- only support IPv4, never try to resolve or contact IPv6 2216- only support IPv4, never try to resolve or contact IPv6
1901addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2217addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1902IPv6, but prefer IPv6 over IPv4. 2218IPv6, but prefer IPv6 over IPv4.
1903 2219
2220=item C<PERL_ANYEVENT_HOSTS>
2221
2222This variable, if specified, overrides the F</etc/hosts> file used by
2223L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2224from that file instead.
2225
1904=item C<PERL_ANYEVENT_EDNS0> 2226=item C<PERL_ANYEVENT_EDNS0>
1905 2227
1906Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2228Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
1907for DNS. This extension is generally useful to reduce DNS traffic, but 2229DNS. This extension is generally useful to reduce DNS traffic, especially
1908some (broken) firewalls drop such DNS packets, which is why it is off by 2230when DNSSEC is involved, but some (broken) firewalls drop such DNS
1909default. 2231packets, which is why it is off by default.
1910 2232
1911Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2233Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1912EDNS0 in its DNS requests. 2234EDNS0 in its DNS requests.
1913 2235
1914=item C<PERL_ANYEVENT_MAX_FORKS> 2236=item C<PERL_ANYEVENT_MAX_FORKS>
1920 2242
1921The default value for the C<max_outstanding> parameter for the default DNS 2243The default value for the C<max_outstanding> parameter for the default DNS
1922resolver - this is the maximum number of parallel DNS requests that are 2244resolver - this is the maximum number of parallel DNS requests that are
1923sent to the DNS server. 2245sent to the DNS server.
1924 2246
2247=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2248
2249Perl has inherently racy signal handling (you can basically choose between
2250losing signals and memory corruption) - pure perl event loops (including
2251C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2252have to poll regularly to avoid losing signals.
2253
2254Some event loops are racy, but don't poll regularly, and some event loops
2255are written in C but are still racy. For those event loops, AnyEvent
2256installs a timer that regularly wakes up the event loop.
2257
2258By default, the interval for this timer is C<10> seconds, but you can
2259override this delay with this environment variable (or by setting
2260the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2261watchers).
2262
2263Lower values increase CPU (and energy) usage, higher values can introduce
2264long delays when reaping children or waiting for signals.
2265
2266The L<AnyEvent::Async> module, if available, will be used to avoid this
2267polling (with most event loops).
2268
1925=item C<PERL_ANYEVENT_RESOLV_CONF> 2269=item C<PERL_ANYEVENT_RESOLV_CONF>
1926 2270
1927The file to use instead of F</etc/resolv.conf> (or OS-specific 2271The absolute path to a F<resolv.conf>-style file to use instead of
1928configuration) in the default resolver. When set to the empty string, no 2272F</etc/resolv.conf> (or the OS-specific configuration) in the default
1929default config will be used. 2273resolver, or the empty string to select the default configuration.
1930 2274
1931=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2275=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1932 2276
1933When neither C<ca_file> nor C<ca_path> was specified during 2277When neither C<ca_file> nor C<ca_path> was specified during
1934L<AnyEvent::TLS> context creation, and either of these environment 2278L<AnyEvent::TLS> context creation, and either of these environment
1935variables exist, they will be used to specify CA certificate locations 2279variables are nonempty, they will be used to specify CA certificate
1936instead of a system-dependent default. 2280locations instead of a system-dependent default.
1937 2281
1938=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2282=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1939 2283
1940When these are set to C<1>, then the respective modules are not 2284When these are set to C<1>, then the respective modules are not
1941loaded. Mostly good for testing AnyEvent itself. 2285loaded. Mostly good for testing AnyEvent itself.
2273(even when used without AnyEvent), but most event loops have acceptable 2617(even when used without AnyEvent), but most event loops have acceptable
2274performance with or without AnyEvent. 2618performance with or without AnyEvent.
2275 2619
2276=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2620=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2277the actual event loop, only with extremely fast event loops such as EV 2621the actual event loop, only with extremely fast event loops such as EV
2278adds AnyEvent significant overhead. 2622does AnyEvent add significant overhead.
2279 2623
2280=item * You should avoid POE like the plague if you want performance or 2624=item * You should avoid POE like the plague if you want performance or
2281reasonable memory usage. 2625reasonable memory usage.
2282 2626
2283=back 2627=back
2582 2926
2583=item L<Time::HiRes> 2927=item L<Time::HiRes>
2584 2928
2585This module is part of perl since release 5.008. It will be used when the 2929This module is part of perl since release 5.008. It will be used when the
2586chosen event library does not come with a timing source of its own. The 2930chosen event library does not come with a timing source of its own. The
2587pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to 2931pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
2588try to use a monotonic clock for timing stability. 2932try to use a monotonic clock for timing stability.
2589 2933
2590=back 2934=back
2591 2935
2592 2936
2654pronounced). 2998pronounced).
2655 2999
2656 3000
2657=head1 SEE ALSO 3001=head1 SEE ALSO
2658 3002
2659Utility functions: L<AnyEvent::Util>. 3003Tutorial/Introduction: L<AnyEvent::Intro>.
2660 3004
2661Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 3005FAQ: L<AnyEvent::FAQ>.
2662L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 3006
3007Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
3008(simply logging).
3009
3010Development/Debugging: L<AnyEvent::Strict> (stricter checking),
3011L<AnyEvent::Debug> (interactive shell, watcher tracing).
3012
3013Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
3014L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
3015L<Qt>, L<POE>, L<FLTK>.
2663 3016
2664Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 3017Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2665L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 3018L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2666L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 3019L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2667L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 3020L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
3021L<AnyEvent::Impl::FLTK>.
2668 3022
2669Non-blocking file handles, sockets, TCP clients and 3023Non-blocking handles, pipes, stream sockets, TCP clients and
2670servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 3024servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2671 3025
3026Asynchronous File I/O: L<AnyEvent::IO>.
3027
2672Asynchronous DNS: L<AnyEvent::DNS>. 3028Asynchronous DNS: L<AnyEvent::DNS>.
2673 3029
2674Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, 3030Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
2675L<Coro::Event>,
2676 3031
2677Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>, 3032Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::IRC>,
2678L<AnyEvent::HTTP>. 3033L<AnyEvent::HTTP>.
2679 3034
2680 3035
2681=head1 AUTHOR 3036=head1 AUTHOR
2682 3037
2683 Marc Lehmann <schmorp@schmorp.de> 3038 Marc Lehmann <schmorp@schmorp.de>
2684 http://home.schmorp.de/ 3039 http://anyevent.schmorp.de
2685 3040
2686=cut 3041=cut
2687 3042
26881 30431
2689 3044

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines