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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines