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.18 by root, Sun Dec 10 21:33:33 2006 UTC vs.
Revision 1.33 by root, Fri Nov 9 19:34:32 2007 UTC

… …
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
… …
157 157
158 $result_ready->wait; 158 $result_ready->wait;
159 159
160=back 160=back
161 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
162=head1 GLOBALS 188=head1 GLOBALS
163 189
164=over 4 190=over 4
165 191
166=item $AnyEvent::MODEL 192=item $AnyEvent::MODEL
… …
171C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 197C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
172AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 198AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
173 199
174The known classes so far are: 200The known classes so far are:
175 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).
176 AnyEvent::Impl::Coro based on Coro::Event, best choise. 204 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
177 AnyEvent::Impl::Event based on Event, also best choice :) 205 AnyEvent::Impl::Event based on Event, also second best choice :)
178 AnyEvent::Impl::Glib based on Glib, second-best choice. 206 AnyEvent::Impl::Glib based on Glib, second-best choice.
179 AnyEvent::Impl::Tk based on Tk, very bad choice. 207 AnyEvent::Impl::Tk based on Tk, very bad choice.
180 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 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.
181 215
182=back 216=back
183 217
184=head1 WHAT TO DO IN A MODULE 218=head1 WHAT TO DO IN A MODULE
185 219
… …
214=cut 248=cut
215 249
216package AnyEvent; 250package AnyEvent;
217 251
218no warnings; 252no warnings;
219use strict 'vars'; 253use strict;
254
220use Carp; 255use Carp;
221 256
222our $VERSION = '2.1'; 257our $VERSION = '2.55';
223our $MODEL; 258our $MODEL;
224 259
225our $AUTOLOAD; 260our $AUTOLOAD;
226our @ISA; 261our @ISA;
227 262
228our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 263our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
229 264
230our @REGISTRY; 265our @REGISTRY;
231 266
232my @models = ( 267my @models = (
268 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
269 [EV:: => AnyEvent::Impl::EV::],
233 [Coro::Event:: => AnyEvent::Impl::Coro::], 270 [Coro::Event:: => AnyEvent::Impl::Coro::],
234 [Event:: => AnyEvent::Impl::Event::], 271 [Event:: => AnyEvent::Impl::Event::],
235 [Glib:: => AnyEvent::Impl::Glib::], 272 [Glib:: => AnyEvent::Impl::Glib::],
236 [Tk:: => AnyEvent::Impl::Tk::], 273 [Tk:: => AnyEvent::Impl::Tk::],
237 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 274 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
238); 275);
239 276
240our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY); 277our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
241 278
242sub AUTOLOAD { 279sub detect() {
243 (my $func = $AUTOLOAD) =~ s/.*://;
244
245 $method{$func}
246 or croak "$func: not a valid method for AnyEvent objects";
247
248 unless ($MODEL) { 280 unless ($MODEL) {
281 no strict 'refs';
282
249 # check for already loaded models 283 # check for already loaded models
250 for (@REGISTRY, @models) { 284 for (@REGISTRY, @models) {
251 my ($package, $model) = @$_; 285 my ($package, $model) = @$_;
252 if (${"$package\::VERSION"} > 0) { 286 if (${"$package\::VERSION"} > 0) {
253 if (eval "require $model") { 287 if (eval "require $model") {
… …
261 unless ($MODEL) { 295 unless ($MODEL) {
262 # try to load a model 296 # try to load a model
263 297
264 for (@REGISTRY, @models) { 298 for (@REGISTRY, @models) {
265 my ($package, $model) = @$_; 299 my ($package, $model) = @$_;
300 if (eval "require $package"
301 and ${"$package\::VERSION"} > 0
266 if (eval "require $model") { 302 and eval "require $model") {
267 $MODEL = $model; 303 $MODEL = $model;
268 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;
269 last; 305 last;
270 } 306 }
271 } 307 }
272 308
273 $MODEL 309 $MODEL
274 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: Event (or Coro+Event), Glib or Tk.";
275 } 311 }
312
313 unshift @ISA, $MODEL;
314 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
276 } 315 }
277 316
278 @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;
279 327
280 my $class = shift; 328 my $class = shift;
281 $class->$func (@_); 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 $PID_IDLE;
379our $WNOHANG;
380
381sub _child_wait {
382 while (0 <= (my $pid = waitpid -1, $WNOHANG)) {
383 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
384 (values %{ $PID_CB{0} || {} });
385 }
386
387 undef $PID_IDLE;
388}
389
390sub child {
391 my (undef, %arg) = @_;
392
393 defined (my $pid = $arg{pid} + 0)
394 or Carp::croak "required option 'pid' is missing";
395
396 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
397
398 unless ($WNOHANG) {
399 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
400 }
401
402 unless ($CHLD_W) {
403 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
404 # child could be a zombie already
405 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait);
406 }
407
408 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
409}
410
411sub AnyEvent::Base::Child::DESTROY {
412 my ($pid, $cb) = @{$_[0]};
413
414 delete $PID_CB{$pid}{$cb};
415 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
416
417 undef $CHLD_W unless keys %PID_CB;
282} 418}
283 419
284=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 420=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
285 421
286If you need to support another event library which isn't directly 422If you need to support another event library which isn't directly
… …
297This tells AnyEvent to (literally) use the C<urxvt::anyevent::> 433This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
298package/class when it finds the C<urxvt> package/module is loaded. When 434package/class when it finds the C<urxvt> package/module is loaded. When
299AnyEvent is loaded and asked to find a suitable event model, it will 435AnyEvent is loaded and asked to find a suitable event model, it will
300first check for the presence of urxvt. 436first check for the presence of urxvt.
301 437
302The class should prove implementations for all watcher types (see 438The class should provide implementations for all watcher types (see
303L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib> 439L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
304(Source code) and so on for actual examples, use C<perldoc -m 440(Source code) and so on for actual examples, use C<perldoc -m
305AnyEvent::Impl::Glib> to see the sources). 441AnyEvent::Impl::Glib> to see the sources).
306 442
307The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt) 443The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
… …
311I<rxvt-unicode> distribution. 447I<rxvt-unicode> distribution.
312 448
313I<rxvt-unicode> also cheats a bit by not providing blocking access to 449I<rxvt-unicode> also cheats a bit by not providing blocking access to
314condition variables: code blocking while waiting for a condition will 450condition variables: code blocking while waiting for a condition will
315C<die>. This still works with most modules/usages, and blocking calls must 451C<die>. This still works with most modules/usages, and blocking calls must
316not be in an interactive appliation, so it makes sense. 452not be in an interactive application, so it makes sense.
317 453
318=head1 ENVIRONMENT VARIABLES 454=head1 ENVIRONMENT VARIABLES
319 455
320The following environment variables are used by this module: 456The following environment variables are used by this module:
321 457

Diff Legend

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