… | |
… | |
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 |
… | |
… | |
303 | =back |
304 | =back |
304 | |
305 | |
305 | =head2 SIGNAL WATCHERS |
306 | =head2 SIGNAL WATCHERS |
306 | |
307 | |
307 | 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 |
308 | 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 |
309 | be invoked whenever a signal occurs. |
310 | callback to be invoked whenever a signal occurs. |
310 | |
311 | |
311 | Although the callback might get passed parameters, their value and |
312 | Although the callback might get passed parameters, their value and |
312 | presence is undefined and you cannot rely on them. Portable AnyEvent |
313 | presence is undefined and you cannot rely on them. Portable AnyEvent |
313 | callbacks cannot use arguments passed to signal watcher callbacks. |
314 | callbacks cannot use arguments passed to signal watcher callbacks. |
314 | |
315 | |
… | |
… | |
938 | $MODEL |
939 | $MODEL |
939 | 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."; |
940 | } |
941 | } |
941 | } |
942 | } |
942 | |
943 | |
|
|
944 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
|
|
945 | |
943 | unshift @ISA, $MODEL; |
946 | unshift @ISA, $MODEL; |
944 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
947 | |
|
|
948 | require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT}; |
945 | |
949 | |
946 | (shift @post_detect)->() while @post_detect; |
950 | (shift @post_detect)->() while @post_detect; |
947 | } |
951 | } |
948 | |
952 | |
949 | $MODEL |
953 | $MODEL |
… | |
… | |
1176 | conditions, such as not being able to load the event model specified by |
1180 | conditions, such as not being able to load the event model specified by |
1177 | C<PERL_ANYEVENT_MODEL>. |
1181 | C<PERL_ANYEVENT_MODEL>. |
1178 | |
1182 | |
1179 | When set to C<2> or higher, cause AnyEvent to report to STDERR which event |
1183 | When set to C<2> or higher, cause AnyEvent to report to STDERR which event |
1180 | model it chooses. |
1184 | model it chooses. |
|
|
1185 | |
|
|
1186 | =item C<PERL_ANYEVENT_STRICT> |
|
|
1187 | |
|
|
1188 | AnyEvent does not do much argument checking by default, as thorough |
|
|
1189 | argument checking is very costly. Setting this variable to a true value |
|
|
1190 | will cause AnyEvent to thoroughly check the arguments passed to most |
|
|
1191 | method calls and croaks if it finds any problems. In other words, enables |
|
|
1192 | "strict" mode. Unlike C<use strict> it is definitely recommended ot keep |
|
|
1193 | it off in production. |
1181 | |
1194 | |
1182 | =item C<PERL_ANYEVENT_MODEL> |
1195 | =item C<PERL_ANYEVENT_MODEL> |
1183 | |
1196 | |
1184 | This can be used to specify the event model to be used by AnyEvent, before |
1197 | This can be used to specify the event model to be used by AnyEvent, before |
1185 | auto detection and -probing kicks in. It must be a string consisting |
1198 | auto detection and -probing kicks in. It must be a string consisting |
… | |
… | |
1682 | |
1695 | |
1683 | use AnyEvent; |
1696 | use AnyEvent; |
1684 | |
1697 | |
1685 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
1698 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
1686 | be used to probe what backend is used and gain other information (which is |
1699 | be used to probe what backend is used and gain other information (which is |
1687 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL). |
1700 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and |
|
|
1701 | $ENV{PERL_ANYEGENT_STRICT}. |
1688 | |
1702 | |
1689 | |
1703 | |
1690 | =head1 BUGS |
1704 | =head1 BUGS |
1691 | |
1705 | |
1692 | Perl 5.8 has numerous memleaks that sometimes hit this module and are hard |
1706 | Perl 5.8 has numerous memleaks that sometimes hit this module and are hard |