… | |
… | |
33 | |
33 | |
34 | Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of |
34 | Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of |
35 | policy> and AnyEvent is I<small and efficient>. |
35 | policy> and AnyEvent is I<small and efficient>. |
36 | |
36 | |
37 | First and foremost, I<AnyEvent is not an event model> itself, it only |
37 | First and foremost, I<AnyEvent is not an event model> itself, it only |
38 | interfaces to whatever event model the main program happens to use in a |
38 | interfaces to whatever event model the main program happens to use, in a |
39 | pragmatic way. For event models and certain classes of immortals alike, |
39 | pragmatic way. For event models and certain classes of immortals alike, |
40 | the statement "there can only be one" is a bitter reality: In general, |
40 | the statement "there can only be one" is a bitter reality: In general, |
41 | only one event loop can be active at the same time in a process. AnyEvent |
41 | only one event loop can be active at the same time in a process. AnyEvent |
42 | helps hiding the differences between those event loops. |
42 | cannot change this, but it can hide the differences between those event |
|
|
43 | loops. |
43 | |
44 | |
44 | The goal of AnyEvent is to offer module authors the ability to do event |
45 | The goal of AnyEvent is to offer module authors the ability to do event |
45 | programming (waiting for I/O or timer events) without subscribing to a |
46 | programming (waiting for I/O or timer events) without subscribing to a |
46 | religion, a way of living, and most importantly: without forcing your |
47 | religion, a way of living, and most importantly: without forcing your |
47 | module users into the same thing by forcing them to use the same event |
48 | module users into the same thing by forcing them to use the same event |
48 | model you use. |
49 | model you use. |
49 | |
50 | |
50 | For modules like POE or IO::Async (which is a total misnomer as it is |
51 | For modules like POE or IO::Async (which is a total misnomer as it is |
51 | actually doing all I/O I<synchronously>...), using them in your module is |
52 | actually doing all I/O I<synchronously>...), using them in your module is |
52 | like joining a cult: After you joined, you are dependent on them and you |
53 | like joining a cult: After you joined, you are dependent on them and you |
53 | cannot use anything else, as it is simply incompatible to everything that |
54 | cannot use anything else, as they are simply incompatible to everything |
54 | isn't itself. What's worse, all the potential users of your module are |
55 | that isn't them. What's worse, all the potential users of your |
55 | I<also> forced to use the same event loop you use. |
56 | module are I<also> forced to use the same event loop you use. |
56 | |
57 | |
57 | AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works |
58 | AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works |
58 | fine. AnyEvent + Tk works fine etc. etc. but none of these work together |
59 | fine. AnyEvent + Tk works fine etc. etc. but none of these work together |
59 | with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if |
60 | with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if |
60 | your module uses one of those, every user of your module has to use it, |
61 | your module uses one of those, every user of your module has to use it, |
61 | too. But if your module uses AnyEvent, it works transparently with all |
62 | too. But if your module uses AnyEvent, it works transparently with all |
62 | event models it supports (including stuff like POE and IO::Async, as long |
63 | event models it supports (including stuff like IO::Async, as long as those |
63 | as those use one of the supported event loops. It is trivial to add new |
64 | use one of the supported event loops. It is trivial to add new event loops |
64 | event loops to AnyEvent, too, so it is future-proof). |
65 | to AnyEvent, too, so it is future-proof). |
65 | |
66 | |
66 | In addition to being free of having to use I<the one and only true event |
67 | In addition to being free of having to use I<the one and only true event |
67 | model>, AnyEvent also is free of bloat and policy: with POE or similar |
68 | model>, AnyEvent also is free of bloat and policy: with POE or similar |
68 | modules, you get an enormous amount of code and strict rules you have to |
69 | modules, you get an enormous amount of code and strict rules you have to |
69 | follow. AnyEvent, on the other hand, is lean and up to the point, by only |
70 | follow. AnyEvent, on the other hand, is lean and up to the point, by only |
… | |
… | |
152 | =head2 I/O WATCHERS |
153 | =head2 I/O WATCHERS |
153 | |
154 | |
154 | You can create an I/O watcher by calling the C<< AnyEvent->io >> method |
155 | You can create an I/O watcher by calling the C<< AnyEvent->io >> method |
155 | with the following mandatory key-value pairs as arguments: |
156 | with the following mandatory key-value pairs as arguments: |
156 | |
157 | |
157 | C<fh> the Perl I<file handle> (I<not> file descriptor) to watch |
158 | C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for events |
158 | for events. C<poll> must be a string that is either C<r> or C<w>, |
159 | (AnyEvent might or might not keep a reference to this file handle). C<poll> |
159 | which creates a watcher waiting for "r"eadable or "w"ritable events, |
160 | must be a string that is either C<r> or C<w>, which creates a watcher |
160 | respectively. C<cb> is the callback to invoke each time the file handle |
161 | waiting for "r"eadable or "w"ritable events, respectively. C<cb> is the |
161 | becomes ready. |
162 | callback to invoke each time the file handle becomes ready. |
162 | |
163 | |
163 | Although the callback might get passed parameters, their value and |
164 | Although the callback might get passed parameters, their value and |
164 | presence is undefined and you cannot rely on them. Portable AnyEvent |
165 | presence is undefined and you cannot rely on them. Portable AnyEvent |
165 | callbacks cannot use arguments passed to I/O watcher callbacks. |
166 | callbacks cannot use arguments passed to I/O watcher callbacks. |
166 | |
167 | |
… | |
… | |
193 | Although the callback might get passed parameters, their value and |
194 | Although the callback might get passed parameters, their value and |
194 | presence is undefined and you cannot rely on them. Portable AnyEvent |
195 | presence is undefined and you cannot rely on them. Portable AnyEvent |
195 | callbacks cannot use arguments passed to time watcher callbacks. |
196 | callbacks cannot use arguments passed to time watcher callbacks. |
196 | |
197 | |
197 | The callback will normally be invoked once only. If you specify another |
198 | The callback will normally be invoked once only. If you specify another |
198 | parameter, C<interval>, as a positive number, then the callback will be |
199 | parameter, C<interval>, as a strictly positive number (> 0), then the |
199 | invoked regularly at that interval (in fractional seconds) after the first |
200 | callback will be invoked regularly at that interval (in fractional |
200 | invocation. |
201 | seconds) after the first invocation. If C<interval> is specified with a |
|
|
202 | false value, then it is treated as if it were missing. |
201 | |
203 | |
202 | The callback will be rescheduled before invoking the callback, but no |
204 | The callback will be rescheduled before invoking the callback, but no |
203 | attempt is done to avoid timer drift in most backends, so the interval is |
205 | attempt is done to avoid timer drift in most backends, so the interval is |
204 | only approximate. |
206 | only approximate. |
205 | |
207 | |
… | |
… | |
302 | =back |
304 | =back |
303 | |
305 | |
304 | =head2 SIGNAL WATCHERS |
306 | =head2 SIGNAL WATCHERS |
305 | |
307 | |
306 | You can watch for signals using a signal watcher, C<signal> is the signal |
308 | You can watch for signals using a signal watcher, C<signal> is the signal |
307 | I<name> without any C<SIG> prefix, C<cb> is the Perl callback to |
309 | I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl |
308 | be invoked whenever a signal occurs. |
310 | callback to be invoked whenever a signal occurs. |
309 | |
311 | |
310 | Although the callback might get passed parameters, their value and |
312 | Although the callback might get passed parameters, their value and |
311 | presence is undefined and you cannot rely on them. Portable AnyEvent |
313 | presence is undefined and you cannot rely on them. Portable AnyEvent |
312 | callbacks cannot use arguments passed to signal watcher callbacks. |
314 | callbacks cannot use arguments passed to signal watcher callbacks. |
313 | |
315 | |
… | |
… | |
937 | $MODEL |
939 | $MODEL |
938 | or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; |
940 | or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; |
939 | } |
941 | } |
940 | } |
942 | } |
941 | |
943 | |
|
|
944 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
|
|
945 | |
942 | unshift @ISA, $MODEL; |
946 | unshift @ISA, $MODEL; |
943 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
947 | |
|
|
948 | require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT}; |
944 | |
949 | |
945 | (shift @post_detect)->() while @post_detect; |
950 | (shift @post_detect)->() while @post_detect; |
946 | } |
951 | } |
947 | |
952 | |
948 | $MODEL |
953 | $MODEL |
… | |
… | |
956 | |
961 | |
957 | detect unless $MODEL; |
962 | detect unless $MODEL; |
958 | |
963 | |
959 | my $class = shift; |
964 | my $class = shift; |
960 | $class->$func (@_); |
965 | $class->$func (@_); |
|
|
966 | } |
|
|
967 | |
|
|
968 | # utility function to dup a filehandle. this is used by many backends |
|
|
969 | # to support binding more than one watcher per filehandle (they usually |
|
|
970 | # allow only one watcher per fd, so we dup it to get a different one). |
|
|
971 | sub _dupfh($$$$) { |
|
|
972 | my ($poll, $fh, $r, $w) = @_; |
|
|
973 | |
|
|
974 | require Fcntl; |
|
|
975 | |
|
|
976 | # cygwin requires the fh mode to be matching, unix doesn't |
|
|
977 | my ($rw, $mode) = $poll eq "r" ? ($r, "<") |
|
|
978 | : $poll eq "w" ? ($w, ">") |
|
|
979 | : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'"; |
|
|
980 | |
|
|
981 | open my $fh2, "$mode&" . fileno $fh |
|
|
982 | or die "cannot dup() filehandle: $!"; |
|
|
983 | |
|
|
984 | # we assume CLOEXEC is already set by perl in all important cases |
|
|
985 | |
|
|
986 | ($fh2, $rw) |
961 | } |
987 | } |
962 | |
988 | |
963 | package AnyEvent::Base; |
989 | package AnyEvent::Base; |
964 | |
990 | |
965 | # default implementation for now and time |
991 | # default implementation for now and time |
… | |
… | |
1175 | conditions, such as not being able to load the event model specified by |
1201 | conditions, such as not being able to load the event model specified by |
1176 | C<PERL_ANYEVENT_MODEL>. |
1202 | C<PERL_ANYEVENT_MODEL>. |
1177 | |
1203 | |
1178 | When set to C<2> or higher, cause AnyEvent to report to STDERR which event |
1204 | When set to C<2> or higher, cause AnyEvent to report to STDERR which event |
1179 | model it chooses. |
1205 | model it chooses. |
|
|
1206 | |
|
|
1207 | =item C<PERL_ANYEVENT_STRICT> |
|
|
1208 | |
|
|
1209 | AnyEvent does not do much argument checking by default, as thorough |
|
|
1210 | argument checking is very costly. Setting this variable to a true value |
|
|
1211 | will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly |
|
|
1212 | check the arguments passed to most method calls. If it finds any problems |
|
|
1213 | it will croak. |
|
|
1214 | |
|
|
1215 | In other words, enables "strict" mode. |
|
|
1216 | |
|
|
1217 | Unlike C<use strict> it is definitely recommended ot keep it off in |
|
|
1218 | production. |
1180 | |
1219 | |
1181 | =item C<PERL_ANYEVENT_MODEL> |
1220 | =item C<PERL_ANYEVENT_MODEL> |
1182 | |
1221 | |
1183 | This can be used to specify the event model to be used by AnyEvent, before |
1222 | This can be used to specify the event model to be used by AnyEvent, before |
1184 | auto detection and -probing kicks in. It must be a string consisting |
1223 | auto detection and -probing kicks in. It must be a string consisting |
… | |
… | |
1681 | |
1720 | |
1682 | use AnyEvent; |
1721 | use AnyEvent; |
1683 | |
1722 | |
1684 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
1723 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
1685 | be used to probe what backend is used and gain other information (which is |
1724 | be used to probe what backend is used and gain other information (which is |
1686 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL). |
1725 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and |
|
|
1726 | $ENV{PERL_ANYEGENT_STRICT}. |
1687 | |
1727 | |
1688 | |
1728 | |
1689 | =head1 BUGS |
1729 | =head1 BUGS |
1690 | |
1730 | |
1691 | Perl 5.8 has numerous memleaks that sometimes hit this module and are hard |
1731 | Perl 5.8 has numerous memleaks that sometimes hit this module and are hard |