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.4 by root, Thu Dec 1 22:04:50 2005 UTC vs.
Revision 1.29 by root, Wed Oct 31 14:17:43 2007 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5Event, Coro, Glib, Tk - various supported event loops 5Event, Coro, Glib, Tk, Perl - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9use AnyEvent; 9 use AnyEvent;
10 10
11 my $w = AnyEvent->timer (fh => ..., poll => "[rw]+", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
12 my ($poll_got) = @_;
13 ... 12 ...
14 }); 13 });
14
15 my $w = AnyEvent->io (after => $seconds, cb => sub { 15 my $w = AnyEvent->timer (after => $seconds, cb => sub {
16 ... 16 ...
17 }); 17 });
18 18
19 # watchers get canceled whenever $w is destroyed 19 my $w = AnyEvent->condvar; # stores wether a condition was flagged
20 # only one watcher per $fh and $poll type is allowed
21 # (i.e. on a socket you cna have one r + one w or one rw
22 # watcher, not any more.
23 # timers can only be used once
24
25 my $w = AnyEvent->condvar; # kind of main loop replacement
26 # can only be used once
27 $w->wait; # enters main loop till $condvar gets ->send 20 $w->wait; # enters "main loop" till $condvar gets ->broadcast
28 $w->broadcast; # wake up waiting and future wait's 21 $w->broadcast; # wake up current and all future wait's
29 22
30=head1 DESCRIPTION 23=head1 DESCRIPTION
31 24
32L<AnyEvent> provides an identical interface to multiple event loops. This 25L<AnyEvent> provides an identical interface to multiple event loops. This
33allows module authors to utilizy an event loop without forcing module 26allows module authors to utilise an event loop without forcing module
34users to use the same event loop (as only a single event loop can coexist 27users to use the same event loop (as only a single event loop can coexist
35peacefully at any one time). 28peacefully at any one time).
36 29
37The interface itself is vaguely similar but not identical to the Event 30The interface itself is vaguely similar but not identical to the Event
38module. 31module.
40On the first call of any method, the module tries to detect the currently 33On the first call of any method, the module tries to detect the currently
41loaded event loop by probing wether any of the following modules is 34loaded event loop by probing wether any of the following modules is
42loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is 35loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is
43used. If none is found, the module tries to load these modules in the 36used. If none is found, the module tries to load these modules in the
44order given. The first one that could be successfully loaded will be 37order given. The first one that could be successfully loaded will be
45used. If still none could be found, it will issue an error. 38used. If still none could be found, AnyEvent will fall back to a pure-perl
39event loop, which is also not very efficient.
40
41Because AnyEvent first checks for modules that are already loaded, loading
42an Event model explicitly before first using AnyEvent will likely make
43that model the default. For example:
44
45 use Tk;
46 use AnyEvent;
47
48 # .. AnyEvent will likely default to Tk
49
50The pure-perl implementation of AnyEvent is called
51C<AnyEvent::Impl::Perl>. Like other event modules you can load it
52explicitly.
53
54=head1 WATCHERS
55
56AnyEvent has the central concept of a I<watcher>, which is an object that
57stores relevant data for each kind of event you are waiting for, such as
58the callback to call, the filehandle to watch, etc.
59
60These watchers are normal Perl objects with normal Perl lifetime. After
61creating a watcher it will immediately "watch" for events and invoke
62the callback. To disable the watcher you have to destroy it (e.g. by
63setting the variable that stores it to C<undef> or otherwise deleting all
64references to it).
65
66All watchers are created by calling a method on the C<AnyEvent> class.
67
68=head2 IO WATCHERS
69
70You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71the following mandatory arguments:
72
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
75a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback
76to invoke everytime the filehandle becomes ready.
77
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
80Tk - if you are sure you are not using Tk this limitation is gone).
81
82Filehandles will be kept alive, so as long as the watcher exists, the
83filehandle exists, too.
84
85Example:
86
87 # wait for readability of STDIN, then read a line and disable the watcher
88 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
89 chomp (my $input = <STDIN>);
90 warn "read: $input\n";
91 undef $w;
92 });
93
94=head2 TIME WATCHERS
95
96You can create a time watcher by calling the C<< AnyEvent->timer >>
97method with the following mandatory arguments:
98
99C<after> after how many seconds (fractions are supported) should the timer
100activate. C<cb> the callback to invoke.
101
102The timer callback will be invoked at most once: if you want a repeating
103timer you have to create a new watcher (this is a limitation by both Tk
104and Glib).
105
106Example:
107
108 # fire an event after 7.7 seconds
109 my $w = AnyEvent->timer (after => 7.7, cb => sub {
110 warn "timeout\n";
111 });
112
113 # to cancel the timer:
114 undef $w
115
116=head2 CONDITION WATCHERS
117
118Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119method without any arguments.
120
121A condition watcher watches for a condition - precisely that the C<<
122->broadcast >> method has been called.
123
124The watcher has only two methods:
46 125
47=over 4 126=over 4
48 127
128=item $cv->wait
129
130Wait (blocking if necessary) until the C<< ->broadcast >> method has been
131called on c<$cv>, while servicing other watchers normally.
132
133Not all event models support a blocking wait - some die in that case, so
134if you are using this from a module, never require a blocking wait, but
135let the caller decide wether the call will block or not (for example,
136by coupling condition variables with some kind of request results and
137supporting callbacks so the caller knows that getting the result will not
138block, while still suppporting blockign waits if the caller so desires).
139
140You can only wait once on a condition - additional calls will return
141immediately.
142
143=item $cv->broadcast
144
145Flag the condition as ready - a running C<< ->wait >> and all further
146calls to C<wait> will return after this method has been called. If nobody
147is waiting the broadcast will be remembered..
148
149Example:
150
151 # wait till the result is ready
152 my $result_ready = AnyEvent->condvar;
153
154 # do something such as adding a timer
155 # or socket watcher the calls $result_ready->broadcast
156 # when the "result" is ready.
157
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. The watcher will only trigger once. This works by
180installing a signal handler for C<SIGCHLD>.
181
182Example: wait for pid 1333
183
184 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
185
186=head1 GLOBALS
187
188=over 4
189
190=item $AnyEvent::MODEL
191
192Contains C<undef> until the first watcher is being created. Then it
193contains the event model that is being used, which is the name of the
194Perl class implementing the model. This class is usually one of the
195C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
196AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
197
198The known classes so far are:
199
200 EV::AnyEvent based on EV (an interface to libev, best choice)
201 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
202 AnyEvent::Impl::Event based on Event, also second best choice :)
203 AnyEvent::Impl::Glib based on Glib, second-best choice.
204 AnyEvent::Impl::Tk based on Tk, very bad choice.
205 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
206
207=item AnyEvent::detect
208
209Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
210necessary. You should only call this function right before you would have
211created an AnyEvent watcher anyway, that is, very late at runtime.
212
213=back
214
215=head1 WHAT TO DO IN A MODULE
216
217As a module author, you should "use AnyEvent" and call AnyEvent methods
218freely, but you should not load a specific event module or rely on it.
219
220Be careful when you create watchers in the module body - Anyevent will
221decide which event module to use as soon as the first method is called, so
222by calling AnyEvent in your module body you force the user of your module
223to load the event module first.
224
225=head1 WHAT TO DO IN THE MAIN PROGRAM
226
227There will always be a single main program - the only place that should
228dictate which event model to use.
229
230If it doesn't care, it can just "use AnyEvent" and use it itself, or not
231do anything special and let AnyEvent decide which implementation to chose.
232
233If the main program relies on a specific event model (for example, in Gtk2
234programs you have to rely on either Glib or Glib::Event), you should load
235it before loading AnyEvent or any module that uses it, generally, as early
236as possible. The reason is that modules might create watchers when they
237are loaded, and AnyEvent will decide on the event model to use as soon as
238it creates watchers, and it might chose the wrong one unless you load the
239correct one yourself.
240
241You can chose to use a rather inefficient pure-perl implementation by
242loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
243generally better.
244
49=cut 245=cut
50 246
51package AnyEvent; 247package AnyEvent;
52 248
53no warnings; 249no warnings;
54use strict 'vars'; 250use strict;
251
55use Carp; 252use Carp;
56 253
57our $VERSION = 0.2; 254our $VERSION = '2.55';
58our $MODEL; 255our $MODEL;
59 256
60our $AUTOLOAD; 257our $AUTOLOAD;
61our @ISA; 258our @ISA;
62 259
260our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
261
262our @REGISTRY;
263
63my @models = ( 264my @models = (
64 [Coro => Coro::Event::], 265 [Coro::Event:: => AnyEvent::Impl::Coro::],
65 [Event => Event::], 266 [EV:: => EV::AnyEvent::],
66 [Glib => Glib::], 267 [Event:: => AnyEvent::Impl::Event::],
67 [Tk => Tk::], 268 [Glib:: => AnyEvent::Impl::Glib::],
269 [Tk:: => AnyEvent::Impl::Tk::],
270 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
68); 271);
69 272
70our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY); 273our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
71 274
72sub AUTOLOAD { 275sub detect() {
73 $AUTOLOAD =~ s/.*://;
74
75 $method{$AUTOLOAD}
76 or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
77
78 unless ($MODEL) { 276 unless ($MODEL) {
277 no strict 'refs';
278
79 # check for already loaded models 279 # check for already loaded models
80 for (@models) { 280 for (@REGISTRY, @models) {
81 my ($model, $package) = @$_; 281 my ($package, $model) = @$_;
82 if (scalar keys %{ *{"$package\::"} }) { 282 if (${"$package\::VERSION"} > 0) {
83 eval "require AnyEvent::Impl::$model"; 283 if (eval "require $model") {
84 last if $MODEL; 284 $MODEL = $model;
285 warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
286 last;
287 }
85 } 288 }
86 } 289 }
87 290
88 unless ($MODEL) { 291 unless ($MODEL) {
89 # try to load a model 292 # try to load a model
90 293
91 for (@models) { 294 for (@REGISTRY, @models) {
92 my ($model, $package) = @$_; 295 my ($package, $model) = @$_;
93 eval "require AnyEvent::Impl::$model"; 296 if (eval "require $package"
94 last if $MODEL; 297 and ${"$package\::VERSION"} > 0
298 and eval "require $model") {
299 $MODEL = $model;
300 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
301 last;
302 }
95 } 303 }
96 304
97 $MODEL 305 $MODEL
98 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk."; 306 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk.";
99 } 307 }
308
309 unshift @ISA, $MODEL;
310 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
100 } 311 }
101 312
102 @ISA = $MODEL; 313 $MODEL
314}
315
316sub AUTOLOAD {
317 (my $func = $AUTOLOAD) =~ s/.*://;
318
319 $method{$func}
320 or croak "$func: not a valid method for AnyEvent objects";
321
322 detect unless $MODEL;
103 323
104 my $class = shift; 324 my $class = shift;
105 $class->$AUTOLOAD (@_); 325 $class->$func (@_);
106} 326}
107 327
108=back 328package AnyEvent::Base;
329
330# default implementation for ->condvar, ->wait, ->broadcast
331
332sub condvar {
333 bless \my $flag, "AnyEvent::Base::CondVar"
334}
335
336sub AnyEvent::Base::CondVar::broadcast {
337 ${$_[0]}++;
338}
339
340sub AnyEvent::Base::CondVar::wait {
341 AnyEvent->one_event while !${$_[0]};
342}
343
344# default implementation for ->signal
345
346our %SIG_CB;
347
348sub signal {
349 my (undef, %arg) = @_;
350
351 my $signal = uc $arg{signal}
352 or Carp::croak "required option 'signal' is missing";
353
354 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
355 $SIG{$signal} ||= sub {
356 $_->() for values %{ $SIG_CB{$signal} || {} };
357 };
358
359 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
360}
361
362sub AnyEvent::Base::Signal::DESTROY {
363 my ($signal, $cb) = @{$_[0]};
364
365 delete $SIG_CB{$signal}{$cb};
366
367 $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
368}
369
370# default implementation for ->child
371
372our %PID_CB;
373our $CHLD_W;
374our $PID_IDLE;
375our $WNOHANG;
376
377sub _child_wait {
378 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
379 $_->() for values %{ (delete $PID_CB{$pid}) || {} };
380 }
381
382 undef $PID_IDLE;
383}
384
385sub child {
386 my (undef, %arg) = @_;
387
388 my $pid = uc $arg{pid}
389 or Carp::croak "required option 'pid' is missing";
390
391 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
392
393 unless ($WNOHANG) {
394 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1;
395 }
396
397 unless ($CHLD_W) {
398 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
399 # child could be a zombie already
400 $PID_IDLE ||= AnyEvent->timer (after => 0, cb => \&_child_wait);
401 }
402
403 bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
404}
405
406sub AnyEvent::Base::Child::DESTROY {
407 my ($pid, $cb) = @{$_[0]};
408
409 delete $PID_CB{$pid}{$cb};
410 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
411
412 undef $CHLD_W unless keys %PID_CB;
413}
414
415=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
416
417If you need to support another event library which isn't directly
418supported by AnyEvent, you can supply your own interface to it by
419pushing, before the first watcher gets created, the package name of
420the event module and the package name of the interface to use onto
421C<@AnyEvent::REGISTRY>. You can do that before and even without loading
422AnyEvent.
423
424Example:
425
426 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
427
428This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
429package/class when it finds the C<urxvt> package/module is loaded. When
430AnyEvent is loaded and asked to find a suitable event model, it will
431first check for the presence of urxvt.
432
433The class should provide implementations for all watcher types (see
434L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
435(Source code) and so on for actual examples, use C<perldoc -m
436AnyEvent::Impl::Glib> to see the sources).
437
438The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
439uses the above line as-is. An interface isn't included in AnyEvent
440because it doesn't make sense outside the embedded interpreter inside
441I<rxvt-unicode>, and it is updated and maintained as part of the
442I<rxvt-unicode> distribution.
443
444I<rxvt-unicode> also cheats a bit by not providing blocking access to
445condition variables: code blocking while waiting for a condition will
446C<die>. This still works with most modules/usages, and blocking calls must
447not be in an interactive application, so it makes sense.
448
449=head1 ENVIRONMENT VARIABLES
450
451The following environment variables are used by this module:
452
453C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, reports which event
454model gets used.
109 455
110=head1 EXAMPLE 456=head1 EXAMPLE
111 457
112The following program uses an io watcher to read data from stdin, a timer 458The following program uses an io watcher to read data from stdin, a timer
113to display a message once per second, and a condvar to exit the program 459to display a message once per second, and a condvar to exit the program
135 481
136 new_timer; # create first timer 482 new_timer; # create first timer
137 483
138 $cv->wait; # wait until user enters /^q/i 484 $cv->wait; # wait until user enters /^q/i
139 485
486=head1 REAL-WORLD EXAMPLE
487
488Consider the L<Net::FCP> module. It features (among others) the following
489API calls, which are to freenet what HTTP GET requests are to http:
490
491 my $data = $fcp->client_get ($url); # blocks
492
493 my $transaction = $fcp->txn_client_get ($url); # does not block
494 $transaction->cb ( sub { ... } ); # set optional result callback
495 my $data = $transaction->result; # possibly blocks
496
497The C<client_get> method works like C<LWP::Simple::get>: it requests the
498given URL and waits till the data has arrived. It is defined to be:
499
500 sub client_get { $_[0]->txn_client_get ($_[1])->result }
501
502And in fact is automatically generated. This is the blocking API of
503L<Net::FCP>, and it works as simple as in any other, similar, module.
504
505More complicated is C<txn_client_get>: It only creates a transaction
506(completion, result, ...) object and initiates the transaction.
507
508 my $txn = bless { }, Net::FCP::Txn::;
509
510It also creates a condition variable that is used to signal the completion
511of the request:
512
513 $txn->{finished} = AnyAvent->condvar;
514
515It then creates a socket in non-blocking mode.
516
517 socket $txn->{fh}, ...;
518 fcntl $txn->{fh}, F_SETFL, O_NONBLOCK;
519 connect $txn->{fh}, ...
520 and !$!{EWOULDBLOCK}
521 and !$!{EINPROGRESS}
522 and Carp::croak "unable to connect: $!\n";
523
524Then it creates a write-watcher which gets called whenever an error occurs
525or the connection succeeds:
526
527 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
528
529And returns this transaction object. The C<fh_ready_w> callback gets
530called as soon as the event loop detects that the socket is ready for
531writing.
532
533The C<fh_ready_w> method makes the socket blocking again, writes the
534request data and replaces the watcher by a read watcher (waiting for reply
535data). The actual code is more complicated, but that doesn't matter for
536this example:
537
538 fcntl $txn->{fh}, F_SETFL, 0;
539 syswrite $txn->{fh}, $txn->{request}
540 or die "connection or write error";
541 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
542
543Again, C<fh_ready_r> waits till all data has arrived, and then stores the
544result and signals any possible waiters that the request ahs finished:
545
546 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
547
548 if (end-of-file or data complete) {
549 $txn->{result} = $txn->{buf};
550 $txn->{finished}->broadcast;
551 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
552 }
553
554The C<result> method, finally, just waits for the finished signal (if the
555request was already finished, it doesn't wait, of course, and returns the
556data:
557
558 $txn->{finished}->wait;
559 return $txn->{result};
560
561The actual code goes further and collects all errors (C<die>s, exceptions)
562that occured during request processing. The C<result> method detects
563wether an exception as thrown (it is stored inside the $txn object)
564and just throws the exception, which means connection errors and other
565problems get reported tot he code that tries to use the result, not in a
566random callback.
567
568All of this enables the following usage styles:
569
5701. Blocking:
571
572 my $data = $fcp->client_get ($url);
573
5742. Blocking, but parallelizing:
575
576 my @datas = map $_->result,
577 map $fcp->txn_client_get ($_),
578 @urls;
579
580Both blocking examples work without the module user having to know
581anything about events.
582
5833a. Event-based in a main program, using any support Event module:
584
585 use Event;
586
587 $fcp->txn_client_get ($url)->cb (sub {
588 my $txn = shift;
589 my $data = $txn->result;
590 ...
591 });
592
593 Event::loop;
594
5953b. The module user could use AnyEvent, too:
596
597 use AnyEvent;
598
599 my $quit = AnyEvent->condvar;
600
601 $fcp->txn_client_get ($url)->cb (sub {
602 ...
603 $quit->broadcast;
604 });
605
606 $quit->wait;
607
140=head1 SEE ALSO 608=head1 SEE ALSO
141 609
142L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>, 610Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>.
143L<AnyEvent::Impl::Coro>, 611
144L<AnyEvent::Impl::Event>, 612Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>.
145L<AnyEvent::Impl::Glib>, 613
146L<AnyEvent::Impl::Tk>. 614Nontrivial usage example: L<Net::FCP>.
147 615
148=head1 616=head1
149 617
150=cut 618=cut
151 619

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines