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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines