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.15 by root, Mon Oct 30 20:55:05 2006 UTC vs.
Revision 1.32 by root, Sat Nov 3 09:29:51 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
… …
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 EV::AnyEvent based on EV (an interface to libev, best choice)
203 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
204 AnyEvent::Impl::Event based on Event, also second best choice :)
205 AnyEvent::Impl::Glib based on Glib, second-best choice.
206 AnyEvent::Impl::Tk based on Tk, very bad choice.
207 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
208
209=item AnyEvent::detect
210
211Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
212necessary. You should only call this function right before you would have
213created an AnyEvent watcher anyway, that is, very late at runtime.
159 214
160=back 215=back
161 216
162=head1 WHAT TO DO IN A MODULE 217=head1 WHAT TO DO IN A MODULE
163 218
… …
192=cut 247=cut
193 248
194package AnyEvent; 249package AnyEvent;
195 250
196no warnings; 251no warnings;
197use strict 'vars'; 252use strict;
253
198use Carp; 254use Carp;
199 255
200our $VERSION = '2.0'; 256our $VERSION = '2.55';
201our $MODEL; 257our $MODEL;
202 258
203our $AUTOLOAD; 259our $AUTOLOAD;
204our @ISA; 260our @ISA;
205 261
206our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 262our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
207 263
208our @REGISTRY; 264our @REGISTRY;
209 265
210my @models = ( 266my @models = (
211 [Coro::Event:: => AnyEvent::Impl::Coro::], 267 [Coro::Event:: => AnyEvent::Impl::Coro::],
268 [EV:: => EV::AnyEvent::],
212 [Event:: => AnyEvent::Impl::Event::], 269 [Event:: => AnyEvent::Impl::Event::],
213 [Glib:: => AnyEvent::Impl::Glib::], 270 [Glib:: => AnyEvent::Impl::Glib::],
214 [Tk:: => AnyEvent::Impl::Tk::], 271 [Tk:: => AnyEvent::Impl::Tk::],
215 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 272 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
216); 273);
217 274
218our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY); 275our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
219 276
220sub AUTOLOAD { 277sub detect() {
221 $AUTOLOAD =~ s/.*://;
222
223 $method{$AUTOLOAD}
224 or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
225
226 unless ($MODEL) { 278 unless ($MODEL) {
279 no strict 'refs';
280
227 # check for already loaded models 281 # check for already loaded models
228 for (@REGISTRY, @models) { 282 for (@REGISTRY, @models) {
229 my ($package, $model) = @$_; 283 my ($package, $model) = @$_;
230 if (${"$package\::VERSION"} > 0) { 284 if (${"$package\::VERSION"} > 0) {
231 if (eval "require $model") { 285 if (eval "require $model") {
… …
239 unless ($MODEL) { 293 unless ($MODEL) {
240 # try to load a model 294 # try to load a model
241 295
242 for (@REGISTRY, @models) { 296 for (@REGISTRY, @models) {
243 my ($package, $model) = @$_; 297 my ($package, $model) = @$_;
298 if (eval "require $package"
299 and ${"$package\::VERSION"} > 0
244 if (eval "require $model") { 300 and eval "require $model") {
245 $MODEL = $model; 301 $MODEL = $model;
246 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 302 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
247 last; 303 last;
248 } 304 }
249 } 305 }
250 306
251 $MODEL 307 $MODEL
252 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk."; 308 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk.";
253 } 309 }
310
311 unshift @ISA, $MODEL;
312 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
254 } 313 }
255 314
256 @ISA = $MODEL; 315 $MODEL
316}
317
318sub AUTOLOAD {
319 (my $func = $AUTOLOAD) =~ s/.*://;
320
321 $method{$func}
322 or croak "$func: not a valid method for AnyEvent objects";
323
324 detect unless $MODEL;
257 325
258 my $class = shift; 326 my $class = shift;
259 $class->$AUTOLOAD (@_); 327 $class->$func (@_);
328}
329
330package AnyEvent::Base;
331
332# default implementation for ->condvar, ->wait, ->broadcast
333
334sub condvar {
335 bless \my $flag, "AnyEvent::Base::CondVar"
336}
337
338sub AnyEvent::Base::CondVar::broadcast {
339 ${$_[0]}++;
340}
341
342sub AnyEvent::Base::CondVar::wait {
343 AnyEvent->one_event while !${$_[0]};
344}
345
346# default implementation for ->signal
347
348our %SIG_CB;
349
350sub signal {
351 my (undef, %arg) = @_;
352
353 my $signal = uc $arg{signal}
354 or Carp::croak "required option 'signal' is missing";
355
356 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
357 $SIG{$signal} ||= sub {
358 $_->() for values %{ $SIG_CB{$signal} || {} };
359 };
360
361 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
362}
363
364sub AnyEvent::Base::Signal::DESTROY {
365 my ($signal, $cb) = @{$_[0]};
366
367 delete $SIG_CB{$signal}{$cb};
368
369 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
370}
371
372# default implementation for ->child
373
374our %PID_CB;
375our $CHLD_W;
376our $PID_IDLE;
377our $WNOHANG;
378
379sub _child_wait {
380 while (0 <= (my $pid = waitpid -1, $WNOHANG)) {
381 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
382 (values %{ $PID_CB{0} || {} });
383 }
384
385 undef $PID_IDLE;
386}
387
388sub child {
389 my (undef, %arg) = @_;
390
391 defined (my $pid = $arg{pid} + 0)
392 or Carp::croak "required option 'pid' is missing";
393
394 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
395
396 unless ($WNOHANG) {
397 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
398 }
399
400 unless ($CHLD_W) {
401 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
402 # child could be a zombie already
403 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait);
404 }
405
406 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
407}
408
409sub AnyEvent::Base::Child::DESTROY {
410 my ($pid, $cb) = @{$_[0]};
411
412 delete $PID_CB{$pid}{$cb};
413 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
414
415 undef $CHLD_W unless keys %PID_CB;
260} 416}
261 417
262=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 418=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
263 419
264If you need to support another event library which isn't directly 420If you need to support another event library which isn't directly
… …
275This tells AnyEvent to (literally) use the C<urxvt::anyevent::> 431This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
276package/class when it finds the C<urxvt> package/module is loaded. When 432package/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 433AnyEvent is loaded and asked to find a suitable event model, it will
278first check for the presence of urxvt. 434first check for the presence of urxvt.
279 435
280The class should prove implementations for all watcher types (see 436The class should provide implementations for all watcher types (see
281L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib> 437L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
282(Source code) and so on for actual examples, use C<perldoc -m 438(Source code) and so on for actual examples, use C<perldoc -m
283AnyEvent::Impl::Glib> to see the sources). 439AnyEvent::Impl::Glib> to see the sources).
284 440
285The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt) 441The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
… …
289I<rxvt-unicode> distribution. 445I<rxvt-unicode> distribution.
290 446
291I<rxvt-unicode> also cheats a bit by not providing blocking access to 447I<rxvt-unicode> also cheats a bit by not providing blocking access to
292condition variables: code blocking while waiting for a condition will 448condition variables: code blocking while waiting for a condition will
293C<die>. This still works with most modules/usages, and blocking calls must 449C<die>. This still works with most modules/usages, and blocking calls must
294not be in an interactive appliation, so it makes sense. 450not be in an interactive application, so it makes sense.
295 451
296=head1 ENVIRONMENT VARIABLES 452=head1 ENVIRONMENT VARIABLES
297 453
298The following environment variables are used by this module: 454The following environment variables are used by this module:
299 455

Diff Legend

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