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.19 by root, Sun Dec 10 23:59:15 2006 UTC vs.
Revision 1.42 by root, Mon Apr 7 19:40:12 2008 UTC

… …
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores wether a condition was flagged 19 my $w = AnyEvent->condvar; # stores wether a condition was flagged
20 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->wait; # enters "main loop" till $condvar gets ->broadcast
21 $w->broadcast; # wake up current and all future wait's 21 $w->broadcast; # wake up current and all future wait's
22
23=head1 WHY YOU SHOULD USE THIS MODULE
24
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent?
27
28Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
29policy> and AnyEvent is I<small and efficient>.
30
31First and foremost, I<AnyEvent is not an event model> itself, it only
32interfaces to whatever event model the main program happens to use in a
33pragmatic way. For event models and certain classes of immortals alike,
34the statement "there can only be one" is a bitter reality, and AnyEvent
35helps hiding the differences.
36
37The goal of AnyEvent is to offer module authors the ability to do event
38programming (waiting for I/O or timer events) without subscribing to a
39religion, a way of living, and most importantly: without forcing your
40module users into the same thing by forcing them to use the same event
41model you use.
42
43For modules like POE or IO::Async (which is actually doing all I/O
44I<synchronously>...), using them in your module is like joining a
45cult: After you joined, you are dependent on them and you cannot use
46anything else, as it is simply incompatible to everything that isn't
47itself.
48
49AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
50works fine etc. etc. but none of these work together with the rest: POE
51+ IO::Async? no go. Tk + Event? no go. If your module uses one of
52those, every user of your module has to use it, too. If your module
53uses AnyEvent, it works transparently with all event models it supports
54(including stuff like POE and IO::Async).
55
56In addition of being free of having to use I<the one and only true event
57model>, AnyEvent also is free of bloat and policy: with POE or similar
58modules, you get an enourmous amount of code and strict rules you have
59to follow. AnyEvent, on the other hand, is lean and to the point by only
60offering the functionality that is useful, in as thin as a wrapper as
61technically possible.
62
22 63
23=head1 DESCRIPTION 64=head1 DESCRIPTION
24 65
25L<AnyEvent> provides an identical interface to multiple event loops. This 66L<AnyEvent> provides an identical interface to multiple event loops. This
26allows module authors to utilise an event loop without forcing module 67allows module authors to utilise an event loop without forcing module
… …
70You can create I/O watcher by calling the C<< AnyEvent->io >> method with 111You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71the following mandatory arguments: 112the following mandatory arguments:
72 113
73C<fh> the Perl I<filehandle> (not filedescriptor) to watch for 114C<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 115events. 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 116a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76to invoke everytime the filehandle becomes ready. 117to invoke everytime the filehandle becomes ready.
77 118
78Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on 119Only 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 120a 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). 121Tk - if you are sure you are not using Tk this limitation is gone).
… …
109 my $w = AnyEvent->timer (after => 7.7, cb => sub { 150 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n"; 151 warn "timeout\n";
111 }); 152 });
112 153
113 # to cancel the timer: 154 # to cancel the timer:
114 undef $w 155 undef $w;
115 156
116=head2 CONDITION WATCHERS 157=head2 CONDITION WATCHERS
117 158
118Condition watchers can be created by calling the C<< AnyEvent->condvar >> 159Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments. 160method without any arguments.
120 161
121A condition watcher watches for a condition - precisely that the C<< 162A condition watcher watches for a condition - precisely that the C<<
122->broadcast >> method has been called. 163->broadcast >> method has been called.
164
165Note that condition watchers recurse into the event loop - if you have
166two watchers that call C<< ->wait >> in a round-robbin fashion, you
167lose. Therefore, condition watchers are good to export to your caller, but
168you should avoid making a blocking wait, at least in callbacks, as this
169usually asks for trouble.
123 170
124The watcher has only two methods: 171The watcher has only two methods:
125 172
126=over 4 173=over 4
127 174
… …
160=back 207=back
161 208
162=head2 SIGNAL WATCHERS 209=head2 SIGNAL WATCHERS
163 210
164You can listen for signals using a signal watcher, C<signal> is the signal 211You can listen for signals using a signal watcher, C<signal> is the signal
165I<name> without any C<SIG> prefix. 212I<name> without any C<SIG> prefix. Multiple signals events can be clumped
213together into one callback invocation, and callback invocation might or
214might not be asynchronous.
166 215
167These watchers might use C<%SIG>, so programs overwriting those signals 216These watchers might use C<%SIG>, so programs overwriting those signals
168directly will likely not work correctly. 217directly will likely not work correctly.
169 218
170Example: exit on SIGINT 219Example: exit on SIGINT
171 220
172 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 221 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
222
223=head2 CHILD PROCESS WATCHERS
224
225You can also listen for the status of a child process specified by the
226C<pid> argument (or any child if the pid argument is 0). The watcher will
227trigger as often as status change for the child are received. This works
228by installing a signal handler for C<SIGCHLD>. The callback will be called with
229the pid and exit status (as returned by waitpid).
230
231Example: wait for pid 1333
232
233 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
173 234
174=head1 GLOBALS 235=head1 GLOBALS
175 236
176=over 4 237=over 4
177 238
… …
183C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 244C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
184AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 245AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
185 246
186The known classes so far are: 247The known classes so far are:
187 248
188 AnyEvent::Impl::Coro based on Coro::Event, best choise. 249 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
250 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
251 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
189 AnyEvent::Impl::Event based on Event, also best choice :) 252 AnyEvent::Impl::Event based on Event, also second best choice :)
190 AnyEvent::Impl::Glib based on Glib, second-best choice. 253 AnyEvent::Impl::Glib based on Glib, second-best choice.
191 AnyEvent::Impl::Tk based on Tk, very bad choice. 254 AnyEvent::Impl::Tk based on Tk, very bad choice.
192 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 255 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
193 256
194=item AnyEvent::detect 257=item AnyEvent::detect
… …
233 296
234package AnyEvent; 297package AnyEvent;
235 298
236no warnings; 299no warnings;
237use strict; 300use strict;
301
238use Carp; 302use Carp;
239 303
240our $VERSION = '2.5'; 304our $VERSION = '3.0';
241our $MODEL; 305our $MODEL;
242 306
243our $AUTOLOAD; 307our $AUTOLOAD;
244our @ISA; 308our @ISA;
245 309
246our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 310our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
247 311
248our @REGISTRY; 312our @REGISTRY;
249 313
250my @models = ( 314my @models = (
315 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
316 [EV:: => AnyEvent::Impl::EV::],
251 [Coro::Event:: => AnyEvent::Impl::Coro::], 317 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
252 [Event:: => AnyEvent::Impl::Event::], 318 [Event:: => AnyEvent::Impl::Event::],
253 [Glib:: => AnyEvent::Impl::Glib::], 319 [Glib:: => AnyEvent::Impl::Glib::],
254 [Tk:: => AnyEvent::Impl::Tk::], 320 [Tk:: => AnyEvent::Impl::Tk::],
255 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 321 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
256); 322);
… …
276 unless ($MODEL) { 342 unless ($MODEL) {
277 # try to load a model 343 # try to load a model
278 344
279 for (@REGISTRY, @models) { 345 for (@REGISTRY, @models) {
280 my ($package, $model) = @$_; 346 my ($package, $model) = @$_;
347 if (eval "require $package"
348 and ${"$package\::VERSION"} > 0
281 if (eval "require $model") { 349 and eval "require $model") {
282 $MODEL = $model; 350 $MODEL = $model;
283 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; 351 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
284 last; 352 last;
285 } 353 }
286 } 354 }
287 355
288 $MODEL 356 $MODEL
289 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk."; 357 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.";
290 } 358 }
291 359
292 unshift @ISA, $MODEL; 360 unshift @ISA, $MODEL;
293 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 361 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
294 } 362 }
… …
308 $class->$func (@_); 376 $class->$func (@_);
309} 377}
310 378
311package AnyEvent::Base; 379package AnyEvent::Base;
312 380
381# default implementation for ->condvar, ->wait, ->broadcast
382
383sub condvar {
384 bless \my $flag, "AnyEvent::Base::CondVar"
385}
386
387sub AnyEvent::Base::CondVar::broadcast {
388 ${$_[0]}++;
389}
390
391sub AnyEvent::Base::CondVar::wait {
392 AnyEvent->one_event while !${$_[0]};
393}
394
313# default implementation for signal 395# default implementation for ->signal
314 396
315our %SIG_CB; 397our %SIG_CB;
316 398
317sub signal { 399sub signal {
318 my (undef, %arg) = @_; 400 my (undef, %arg) = @_;
319 401
320 my $signal = uc $arg{signal} 402 my $signal = uc $arg{signal}
321 or Carp::croak "required option 'signal' is missing"; 403 or Carp::croak "required option 'signal' is missing";
322 404
323 my $w = bless [$signal, $arg{cb}], "AnyEvent::Base::Signal";
324
325 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 405 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
326 $SIG{$signal} ||= sub { 406 $SIG{$signal} ||= sub {
327 $_->() for values %{ $SIG_CB{$signal} }; 407 $_->() for values %{ $SIG_CB{$signal} || {} };
328 }; 408 };
329 409
330 $w 410 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
331} 411}
332 412
333sub AnyEvent::Base::Signal::DESTROY { 413sub AnyEvent::Base::Signal::DESTROY {
334 my ($signal, $cb) = @{$_[0]}; 414 my ($signal, $cb) = @{$_[0]};
335 415
336 delete $SIG_CB{$signal}{$cb}; 416 delete $SIG_CB{$signal}{$cb};
337 417
338 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; 418 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
419}
420
421# default implementation for ->child
422
423our %PID_CB;
424our $CHLD_W;
425our $CHLD_DELAY_W;
426our $PID_IDLE;
427our $WNOHANG;
428
429sub _child_wait {
430 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
431 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
432 (values %{ $PID_CB{0} || {} });
433 }
434
435 undef $PID_IDLE;
436}
437
438sub _sigchld {
439 # make sure we deliver these changes "synchronous" with the event loop.
440 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
441 undef $CHLD_DELAY_W;
442 &_child_wait;
443 });
444}
445
446sub child {
447 my (undef, %arg) = @_;
448
449 defined (my $pid = $arg{pid} + 0)
450 or Carp::croak "required option 'pid' is missing";
451
452 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
453
454 unless ($WNOHANG) {
455 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
456 }
457
458 unless ($CHLD_W) {
459 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
460 # child could be a zombie already, so make at least one round
461 &_sigchld;
462 }
463
464 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
465}
466
467sub AnyEvent::Base::Child::DESTROY {
468 my ($pid, $cb) = @{$_[0]};
469
470 delete $PID_CB{$pid}{$cb};
471 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
472
473 undef $CHLD_W unless keys %PID_CB;
339} 474}
340 475
341=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 476=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
342 477
343If you need to support another event library which isn't directly 478If you need to support another event library which isn't directly
… …
368I<rxvt-unicode> distribution. 503I<rxvt-unicode> distribution.
369 504
370I<rxvt-unicode> also cheats a bit by not providing blocking access to 505I<rxvt-unicode> also cheats a bit by not providing blocking access to
371condition variables: code blocking while waiting for a condition will 506condition variables: code blocking while waiting for a condition will
372C<die>. This still works with most modules/usages, and blocking calls must 507C<die>. This still works with most modules/usages, and blocking calls must
373not be in an interactive appliation, so it makes sense. 508not be in an interactive application, so it makes sense.
374 509
375=head1 ENVIRONMENT VARIABLES 510=head1 ENVIRONMENT VARIABLES
376 511
377The following environment variables are used by this module: 512The following environment variables are used by this module:
378 513

Diff Legend

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