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.166 by root, Tue Jul 8 23:10:20 2008 UTC vs.
Revision 1.168 by root, Tue Jul 8 23:53:37 2008 UTC

… …
33 33
34Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of 34Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
35policy> and AnyEvent is I<small and efficient>. 35policy> and AnyEvent is I<small and efficient>.
36 36
37First and foremost, I<AnyEvent is not an event model> itself, it only 37First and foremost, I<AnyEvent is not an event model> itself, it only
38interfaces to whatever event model the main program happens to use in a 38interfaces to whatever event model the main program happens to use, in a
39pragmatic way. For event models and certain classes of immortals alike, 39pragmatic way. For event models and certain classes of immortals alike,
40the statement "there can only be one" is a bitter reality: In general, 40the statement "there can only be one" is a bitter reality: In general,
41only one event loop can be active at the same time in a process. AnyEvent 41only one event loop can be active at the same time in a process. AnyEvent
42helps hiding the differences between those event loops. 42cannot change this, but it can hide the differences between those event
43loops.
43 44
44The goal of AnyEvent is to offer module authors the ability to do event 45The goal of AnyEvent is to offer module authors the ability to do event
45programming (waiting for I/O or timer events) without subscribing to a 46programming (waiting for I/O or timer events) without subscribing to a
46religion, a way of living, and most importantly: without forcing your 47religion, a way of living, and most importantly: without forcing your
47module users into the same thing by forcing them to use the same event 48module users into the same thing by forcing them to use the same event
48model you use. 49model you use.
49 50
50For modules like POE or IO::Async (which is a total misnomer as it is 51For modules like POE or IO::Async (which is a total misnomer as it is
51actually doing all I/O I<synchronously>...), using them in your module is 52actually doing all I/O I<synchronously>...), using them in your module is
52like joining a cult: After you joined, you are dependent on them and you 53like joining a cult: After you joined, you are dependent on them and you
53cannot use anything else, as it is simply incompatible to everything that 54cannot use anything else, as they are simply incompatible to everything
54isn't itself. What's worse, all the potential users of your module are 55that isn't them. What's worse, all the potential users of your
55I<also> forced to use the same event loop you use. 56module are I<also> forced to use the same event loop you use.
56 57
57AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 58AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
58fine. AnyEvent + Tk works fine etc. etc. but none of these work together 59fine. AnyEvent + Tk works fine etc. etc. but none of these work together
59with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if 60with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
60your module uses one of those, every user of your module has to use it, 61your module uses one of those, every user of your module has to use it,
61too. But if your module uses AnyEvent, it works transparently with all 62too. But if your module uses AnyEvent, it works transparently with all
62event models it supports (including stuff like POE and IO::Async, as long 63event models it supports (including stuff like IO::Async, as long as those
63as those use one of the supported event loops. It is trivial to add new 64use one of the supported event loops. It is trivial to add new event loops
64event loops to AnyEvent, too, so it is future-proof). 65to AnyEvent, too, so it is future-proof).
65 66
66In addition to being free of having to use I<the one and only true event 67In addition to being free of having to use I<the one and only true event
67model>, AnyEvent also is free of bloat and policy: with POE or similar 68model>, AnyEvent also is free of bloat and policy: with POE or similar
68modules, you get an enormous amount of code and strict rules you have to 69modules, you get an enormous amount of code and strict rules you have to
69follow. AnyEvent, on the other hand, is lean and up to the point, by only 70follow. 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
307You can watch for signals using a signal watcher, C<signal> is the signal 308You can watch for signals using a signal watcher, C<signal> is the signal
308I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 309I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
309be invoked whenever a signal occurs. 310callback to be invoked whenever a signal occurs.
310 311
311Although the callback might get passed parameters, their value and 312Although the callback might get passed parameters, their value and
312presence is undefined and you cannot rely on them. Portable AnyEvent 313presence is undefined and you cannot rely on them. Portable AnyEvent
313callbacks cannot use arguments passed to signal watcher callbacks. 314callbacks 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
… …
1176conditions, such as not being able to load the event model specified by 1180conditions, such as not being able to load the event model specified by
1177C<PERL_ANYEVENT_MODEL>. 1181C<PERL_ANYEVENT_MODEL>.
1178 1182
1179When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1183When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1180model it chooses. 1184model it chooses.
1185
1186=item C<PERL_ANYEVENT_STRICT>
1187
1188AnyEvent does not do much argument checking by default, as thorough
1189argument checking is very costly. Setting this variable to a true value
1190will cause AnyEvent to thoroughly check the arguments passed to most
1191method 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
1193it off in production.
1181 1194
1182=item C<PERL_ANYEVENT_MODEL> 1195=item C<PERL_ANYEVENT_MODEL>
1183 1196
1184This can be used to specify the event model to be used by AnyEvent, before 1197This can be used to specify the event model to be used by AnyEvent, before
1185auto detection and -probing kicks in. It must be a string consisting 1198auto detection and -probing kicks in. It must be a string consisting
… …
1682 1695
1683 use AnyEvent; 1696 use AnyEvent;
1684 1697
1685Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1698Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1686be used to probe what backend is used and gain other information (which is 1699be used to probe what backend is used and gain other information (which is
1687probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1700probably 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
1692Perl 5.8 has numerous memleaks that sometimes hit this module and are hard 1706Perl 5.8 has numerous memleaks that sometimes hit this module and are hard

Diff Legend

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