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.167 by root, Tue Jul 8 23:44:51 2008 UTC vs.
Revision 1.171 by root, Wed Jul 16 21:17:59 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
… …
825no warnings; 826no warnings;
826use strict; 827use strict;
827 828
828use Carp; 829use Carp;
829 830
830our $VERSION = 4.2; 831our $VERSION = 4.21;
831our $MODEL; 832our $MODEL;
832 833
833our $AUTOLOAD; 834our $AUTOLOAD;
834our @ISA; 835our @ISA;
835 836
… …
940 } 941 }
941 } 942 }
942 943
943 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 944 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
944 945
945 if ($ENV{PERL_ANYEVENT_STRICT}) {
946 unshift @AnyEvent::Base::Strict::ISA, $MODEL;
947 unshift @ISA, AnyEvent::Base::Strict::
948 } else {
949 unshift @ISA, $MODEL; 946 unshift @ISA, $MODEL;
950 } 947
948 require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT};
951 949
952 (shift @post_detect)->() while @post_detect; 950 (shift @post_detect)->() while @post_detect;
953 } 951 }
954 952
955 $MODEL 953 $MODEL
… …
963 961
964 detect unless $MODEL; 962 detect unless $MODEL;
965 963
966 my $class = shift; 964 my $class = shift;
967 $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).
971sub _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)
968} 987}
969 988
970package AnyEvent::Base; 989package AnyEvent::Base;
971 990
972# default implementation for now and time 991# default implementation for now and time
… …
1121 1140
1122# undocumented/compatibility with pre-3.4 1141# undocumented/compatibility with pre-3.4
1123*broadcast = \&send; 1142*broadcast = \&send;
1124*wait = \&_wait; 1143*wait = \&_wait;
1125 1144
1126package AnyEvent::Base::Strict;
1127
1128use Carp qw(croak);
1129
1130# supply checks for argument validity for many functions
1131
1132sub io {
1133 my $class = shift;
1134 my %arg = @_;
1135
1136 ref $arg{cb}
1137 or croak "AnyEvent->io called with illegal cb argument '$arg{cb}'";
1138 delete $arg{cb};
1139
1140 fileno $arg{fh}
1141 or croak "AnyEvent->io called with illegal fh argument '$arg{fh}'";
1142 delete $arg{fh};
1143
1144 $arg{poll} =~ /^[rw]$/
1145 or croak "AnyEvent->io called with illegal poll argument '$arg{poll}'";
1146 delete $arg{poll};
1147
1148 croak "AnyEvent->io called with unsupported parameter(s) " . join ", ", keys %arg
1149 if keys %arg;
1150
1151 $class->SUPER::io (@_)
1152}
1153
1154sub timer {
1155 my $class = shift;
1156 my %arg = @_;
1157
1158 ref $arg{cb}
1159 or croak "AnyEvent->timer called with illegal cb argument '$arg{cb}'";
1160 delete $arg{cb};
1161
1162 exists $arg{after}
1163 or croak "AnyEvent->timer called without mandatory 'after' parameter";
1164 delete $arg{after};
1165
1166 $arg{interval} > 0 || !$arg{interval}
1167 or croak "AnyEvent->timer called with illegal interval argument '$arg{interval}'";
1168 delete $arg{interval};
1169
1170 croak "AnyEvent->timer called with unsupported parameter(s) " . join ", ", keys %arg
1171 if keys %arg;
1172
1173 $class->SUPER::timer (@_)
1174}
1175
1176sub signal {
1177 my $class = shift;
1178 my %arg = @_;
1179
1180 ref $arg{cb}
1181 or croak "AnyEvent->signal called with illegal cb argument '$arg{cb}'";
1182 delete $arg{cb};
1183
1184 eval "require POSIX; defined &POSIX::SIG$arg{signal}"
1185 or croak "AnyEvent->signal called with illegal signal name '$arg{signal}'";
1186 delete $arg{signal};
1187
1188 croak "AnyEvent->signal called with unsupported parameter(s) " . join ", ", keys %arg
1189 if keys %arg;
1190
1191 $class->SUPER::signal (@_)
1192}
1193
1194sub child {
1195 my $class = shift;
1196 my %arg = @_;
1197
1198 ref $arg{cb}
1199 or croak "AnyEvent->signal called with illegal cb argument '$arg{cb}'";
1200 delete $arg{cb};
1201
1202 $arg{pid} =~ /^-?\d+$/
1203 or croak "AnyEvent->signal called with illegal pid value '$arg{pid}'";
1204 delete $arg{pid};
1205
1206 croak "AnyEvent->signal called with unsupported parameter(s) " . join ", ", keys %arg
1207 if keys %arg;
1208
1209 $class->SUPER::child (@_)
1210}
1211
1212sub condvar {
1213 my $class = shift;
1214 my %arg = @_;
1215
1216 !exists $arg{cb} or ref $arg{cb}
1217 or croak "AnyEvent->condvar called with illegal cb argument '$arg{cb}'";
1218 delete $arg{cb};
1219
1220 croak "AnyEvent->condvar called with unsupported parameter(s) " . join ", ", keys %arg
1221 if keys %arg;
1222
1223 $class->SUPER::condvar (@_)
1224}
1225
1226sub time {
1227 my $class = shift;
1228
1229 @_
1230 and croak "AnyEvent->time wrongly called with paramaters";
1231
1232 $class->SUPER::time (@_)
1233}
1234
1235sub now {
1236 my $class = shift;
1237
1238 @_
1239 and croak "AnyEvent->now wrongly called with paramaters";
1240
1241 $class->SUPER::now (@_)
1242}
1243
1244=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1145=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1245 1146
1246This is an advanced topic that you do not normally need to use AnyEvent in 1147This is an advanced topic that you do not normally need to use AnyEvent in
1247a module. This section is only of use to event loop authors who want to 1148a module. This section is only of use to event loop authors who want to
1248provide AnyEvent compatibility. 1149provide AnyEvent compatibility.
… …
1305 1206
1306=item C<PERL_ANYEVENT_STRICT> 1207=item C<PERL_ANYEVENT_STRICT>
1307 1208
1308AnyEvent does not do much argument checking by default, as thorough 1209AnyEvent does not do much argument checking by default, as thorough
1309argument checking is very costly. Setting this variable to a true value 1210argument checking is very costly. Setting this variable to a true value
1310will cause AnyEvent to thoroughly check the arguments passed to most 1211will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1311method calls and croaks if it finds any problems. In other words, enables 1212check the arguments passed to most method calls. If it finds any problems
1213it will croak.
1214
1215In other words, enables "strict" mode.
1216
1312"strict" mode. Unlike C<use strict> it is definitely recommended ot keep 1217Unlike C<use strict> it is definitely recommended ot keep it off in
1313it off in production. 1218production.
1314 1219
1315=item C<PERL_ANYEVENT_MODEL> 1220=item C<PERL_ANYEVENT_MODEL>
1316 1221
1317This can be used to specify the event model to be used by AnyEvent, before 1222This can be used to specify the event model to be used by AnyEvent, before
1318auto detection and -probing kicks in. It must be a string consisting 1223auto detection and -probing kicks in. It must be a string consisting

Diff Legend

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