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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines