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.14 by root, Mon Oct 30 20:52:24 2006 UTC vs.
Revision 1.38 by root, Sun Nov 25 14:08:12 2007 UTC

… …
70You can create I/O watcher by calling the C<< AnyEvent->io >> method with 70You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71the following mandatory arguments: 71the following mandatory arguments:
72 72
73C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 73C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
74events. C<poll> must be a string that is either C<r> or C<w>, that creates 74events. C<poll> must be a string that is either C<r> or C<w>, that creates
75a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback 75a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76to invoke everytime the filehandle becomes ready. 76to invoke everytime the filehandle becomes ready.
77 77
78Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on 78Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
79a socket you can have one r + one w, not any more (limitation comes from 79a socket you can have one r + one w, not any more (limitation comes from
80Tk - if you are sure you are not using Tk this limitation is gone). 80Tk - if you are sure you are not using Tk this limitation is gone).
… …
89 chomp (my $input = <STDIN>); 89 chomp (my $input = <STDIN>);
90 warn "read: $input\n"; 90 warn "read: $input\n";
91 undef $w; 91 undef $w;
92 }); 92 });
93 93
94=head2 TIMER WATCHERS 94=head2 TIME WATCHERS
95 95
96You can create a timer watcher by calling the C<< AnyEvent->timer >> 96You can create a time watcher by calling the C<< AnyEvent->timer >>
97method with the following mandatory arguments: 97method with the following mandatory arguments:
98 98
99C<after> after how many seconds (fractions are supported) should the timer 99C<after> after how many seconds (fractions are supported) should the timer
100activate. C<cb> the callback to invoke. 100activate. C<cb> the callback to invoke.
101 101
… …
109 my $w = AnyEvent->timer (after => 7.7, cb => sub { 109 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n"; 110 warn "timeout\n";
111 }); 111 });
112 112
113 # to cancel the timer: 113 # to cancel the timer:
114 undef $w 114 undef $w;
115 115
116=head2 CONDITION WATCHERS 116=head2 CONDITION WATCHERS
117 117
118Condition watchers can be created by calling the C<< AnyEvent->condvar >> 118Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments. 119method without any arguments.
… …
154 # do something such as adding a timer 154 # do something such as adding a timer
155 # or socket watcher the calls $result_ready->broadcast 155 # or socket watcher the calls $result_ready->broadcast
156 # when the "result" is ready. 156 # when the "result" is ready.
157 157
158 $result_ready->wait; 158 $result_ready->wait;
159
160=back
161
162=head2 SIGNAL WATCHERS
163
164You can listen for signals using a signal watcher, C<signal> is the signal
165I<name> without any C<SIG> prefix. Multiple signals events can be clumped
166together into one callback invocation, and callback invocation might or
167might not be asynchronous.
168
169These watchers might use C<%SIG>, so programs overwriting those signals
170directly will likely not work correctly.
171
172Example: exit on SIGINT
173
174 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
175
176=head2 CHILD PROCESS WATCHERS
177
178You can also listen for the status of a child process specified by the
179C<pid> argument (or any child if the pid argument is 0). The watcher will
180trigger as often as status change for the child are received. This works
181by installing a signal handler for C<SIGCHLD>. The callback will be called with
182the pid and exit status (as returned by waitpid).
183
184Example: wait for pid 1333
185
186 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
187
188=head1 GLOBALS
189
190=over 4
191
192=item $AnyEvent::MODEL
193
194Contains C<undef> until the first watcher is being created. Then it
195contains the event model that is being used, which is the name of the
196Perl class implementing the model. This class is usually one of the
197C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
198AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
199
200The known classes so far are:
201
202 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
203 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
204 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
205 AnyEvent::Impl::Event based on Event, also second best choice :)
206 AnyEvent::Impl::Glib based on Glib, second-best choice.
207 AnyEvent::Impl::Tk based on Tk, very bad choice.
208 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
209
210=item AnyEvent::detect
211
212Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
213necessary. You should only call this function right before you would have
214created an AnyEvent watcher anyway, that is, very late at runtime.
159 215
160=back 216=back
161 217
162=head1 WHAT TO DO IN A MODULE 218=head1 WHAT TO DO IN A MODULE
163 219
… …
192=cut 248=cut
193 249
194package AnyEvent; 250package AnyEvent;
195 251
196no warnings; 252no warnings;
197use strict 'vars'; 253use strict;
254
198use Carp; 255use Carp;
199 256
200our $VERSION = '1.02'; 257our $VERSION = '2.8';
201our $MODEL; 258our $MODEL;
202 259
203our $AUTOLOAD; 260our $AUTOLOAD;
204our @ISA; 261our @ISA;
205 262
206our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 263our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
207 264
208our @REGISTRY; 265our @REGISTRY;
209 266
210my @models = ( 267my @models = (
268 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
269 [EV:: => AnyEvent::Impl::EV::],
211 [Coro::Event:: => AnyEvent::Impl::Coro::], 270 [Coro::Event:: => AnyEvent::Impl::Coro::],
212 [Event:: => AnyEvent::Impl::Event::], 271 [Event:: => AnyEvent::Impl::Event::],
213 [Glib:: => AnyEvent::Impl::Glib::], 272 [Glib:: => AnyEvent::Impl::Glib::],
214 [Tk:: => AnyEvent::Impl::Tk::], 273 [Tk:: => AnyEvent::Impl::Tk::],
215 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 274 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
216); 275);
217 276
218our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY); 277our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
219 278
220sub AUTOLOAD { 279sub detect() {
221 $AUTOLOAD =~ s/.*://;
222
223 $method{$AUTOLOAD}
224 or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
225
226 unless ($MODEL) { 280 unless ($MODEL) {
281 no strict 'refs';
282
227 # check for already loaded models 283 # check for already loaded models
228 for (@REGISTRY, @models) { 284 for (@REGISTRY, @models) {
229 my ($package, $model) = @$_; 285 my ($package, $model) = @$_;
230 if (${"$package\::VERSION"} > 0) { 286 if (${"$package\::VERSION"} > 0) {
231 if (eval "require $model") { 287 if (eval "require $model") {
… …
239 unless ($MODEL) { 295 unless ($MODEL) {
240 # try to load a model 296 # try to load a model
241 297
242 for (@REGISTRY, @models) { 298 for (@REGISTRY, @models) {
243 my ($package, $model) = @$_; 299 my ($package, $model) = @$_;
300 if (eval "require $package"
301 and ${"$package\::VERSION"} > 0
244 if (eval "require $model") { 302 and eval "require $model") {
245 $MODEL = $model; 303 $MODEL = $model;
246 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 304 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
247 last; 305 last;
248 } 306 }
249 } 307 }
250 308
251 $MODEL 309 $MODEL
252 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk."; 310 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event), Glib or Tk.";
253 } 311 }
312
313 unshift @ISA, $MODEL;
314 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
254 } 315 }
255 316
256 @ISA = $MODEL; 317 $MODEL
318}
319
320sub AUTOLOAD {
321 (my $func = $AUTOLOAD) =~ s/.*://;
322
323 $method{$func}
324 or croak "$func: not a valid method for AnyEvent objects";
325
326 detect unless $MODEL;
257 327
258 my $class = shift; 328 my $class = shift;
259 $class->$AUTOLOAD (@_); 329 $class->$func (@_);
330}
331
332package AnyEvent::Base;
333
334# default implementation for ->condvar, ->wait, ->broadcast
335
336sub condvar {
337 bless \my $flag, "AnyEvent::Base::CondVar"
338}
339
340sub AnyEvent::Base::CondVar::broadcast {
341 ${$_[0]}++;
342}
343
344sub AnyEvent::Base::CondVar::wait {
345 AnyEvent->one_event while !${$_[0]};
346}
347
348# default implementation for ->signal
349
350our %SIG_CB;
351
352sub signal {
353 my (undef, %arg) = @_;
354
355 my $signal = uc $arg{signal}
356 or Carp::croak "required option 'signal' is missing";
357
358 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
359 $SIG{$signal} ||= sub {
360 $_->() for values %{ $SIG_CB{$signal} || {} };
361 };
362
363 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
364}
365
366sub AnyEvent::Base::Signal::DESTROY {
367 my ($signal, $cb) = @{$_[0]};
368
369 delete $SIG_CB{$signal}{$cb};
370
371 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
372}
373
374# default implementation for ->child
375
376our %PID_CB;
377our $CHLD_W;
378our $CHLD_DELAY_W;
379our $PID_IDLE;
380our $WNOHANG;
381
382sub _child_wait {
383 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
384 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
385 (values %{ $PID_CB{0} || {} });
386 }
387
388 undef $PID_IDLE;
389}
390
391sub _sigchld {
392 # make sure we deliver these changes "synchronous" with the event loop.
393 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
394 undef $CHLD_DELAY_W;
395 &_child_wait;
396 });
397}
398
399sub child {
400 my (undef, %arg) = @_;
401
402 defined (my $pid = $arg{pid} + 0)
403 or Carp::croak "required option 'pid' is missing";
404
405 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
406
407 unless ($WNOHANG) {
408 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
409 }
410
411 unless ($CHLD_W) {
412 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
413 # child could be a zombie already, so make at least one round
414 &_sigchld;
415 }
416
417 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
418}
419
420sub AnyEvent::Base::Child::DESTROY {
421 my ($pid, $cb) = @{$_[0]};
422
423 delete $PID_CB{$pid}{$cb};
424 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
425
426 undef $CHLD_W unless keys %PID_CB;
260} 427}
261 428
262=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 429=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
263 430
264If you need to support another event library which isn't directly 431If you need to support another event library which isn't directly
… …
275This tells AnyEvent to (literally) use the C<urxvt::anyevent::> 442This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
276package/class when it finds the C<urxvt> package/module is loaded. When 443package/class when it finds the C<urxvt> package/module is loaded. When
277AnyEvent is loaded and asked to find a suitable event model, it will 444AnyEvent is loaded and asked to find a suitable event model, it will
278first check for the presence of urxvt. 445first check for the presence of urxvt.
279 446
280The class should prove implementations for all watcher types (see 447The class should provide implementations for all watcher types (see
281L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib> 448L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
282(Source code) and so on for actual examples, use C<perldoc -m 449(Source code) and so on for actual examples, use C<perldoc -m
283AnyEvent::Impl::Glib> to see the sources). 450AnyEvent::Impl::Glib> to see the sources).
284 451
285The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt) 452The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
… …
289I<rxvt-unicode> distribution. 456I<rxvt-unicode> distribution.
290 457
291I<rxvt-unicode> also cheats a bit by not providing blocking access to 458I<rxvt-unicode> also cheats a bit by not providing blocking access to
292condition variables: code blocking while waiting for a condition will 459condition variables: code blocking while waiting for a condition will
293C<die>. This still works with most modules/usages, and blocking calls must 460C<die>. This still works with most modules/usages, and blocking calls must
294not be in an interactive appliation, so it makes sense. 461not be in an interactive application, so it makes sense.
295 462
296=head1 ENVIRONMENT VARIABLES 463=head1 ENVIRONMENT VARIABLES
297 464
298The following environment variables are used by this module: 465The following environment variables are used by this module:
299 466

Diff Legend

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