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.6 by root, Mon Dec 19 17:03:29 2005 UTC vs.
Revision 1.13 by root, Thu Jul 20 08:26:00 2006 UTC

… …
4 4
5Event, Coro, Glib, Tk - various supported event loops 5Event, Coro, Glib, Tk - 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->io (fh => ..., poll => "[rw]+", cb => sub { 11 my $w = AnyEvent->io (fh => ..., poll => "[rw]+", cb => sub {
12 my ($poll_got) = @_; 12 my ($poll_got) = @_;
13 ... 13 ...
14 }); 14 });
15 15
16- only one io watcher per $fh and $poll type is allowed 16* only one io watcher per $fh and $poll type is allowed (i.e. on a socket
17(i.e. on a socket you can have one r + one w or one rw 17you can have one r + one w or one rw watcher, not any more (limitation by
18watcher, not any more. 18Tk).
19 19
20* the C<$poll_got> passed to the handler needs to be checked by looking
21for single characters (e.g. with a regex), as it can contain more event
22types than were requested (e.g. a 'w' watcher might generate 'rw' events,
23limitation by Glib).
24
20- AnyEvent will keep filehandles alive, so as long as the watcher exists, 25* AnyEvent will keep filehandles alive, so as long as the watcher exists,
21the filehandle exists. 26the filehandle exists.
22 27
23 my $w = AnyEvent->timer (after => $seconds, cb => sub { 28 my $w = AnyEvent->timer (after => $seconds, cb => sub {
24 ... 29 ...
25 }); 30 });
26 31
27- io and time watchers get canceled whenever $w is destroyed, so keep a copy 32* io and time watchers get canceled whenever $w is destroyed, so keep a copy
28 33
29- timers can only be used once and must be recreated for repeated operation 34* timers can only be used once and must be recreated for repeated
35operation (limitation by Glib and Tk).
30 36
31 my $w = AnyEvent->condvar; # kind of main loop replacement 37 my $w = AnyEvent->condvar; # kind of main loop replacement
32 $w->wait; # enters main loop till $condvar gets ->broadcast 38 $w->wait; # enters main loop till $condvar gets ->broadcast
33 $w->broadcast; # wake up current and all future wait's 39 $w->broadcast; # wake up current and all future wait's
34 40
35- condvars are used to give blocking behaviour when neccessary. Create 41* condvars are used to give blocking behaviour when neccessary. Create
36a condvar for any "request" or "event" your module might create, C<< 42a condvar for any "request" or "event" your module might create, C<<
37->broadcast >> it when the event happens and provide a function that calls 43->broadcast >> it when the event happens and provide a function that calls
38C<< ->wait >> for it. See the examples below. 44C<< ->wait >> for it. See the examples below.
39 45
40=head1 DESCRIPTION 46=head1 DESCRIPTION
41 47
42L<AnyEvent> provides an identical interface to multiple event loops. This 48L<AnyEvent> provides an identical interface to multiple event loops. This
43allows module authors to utilizy an event loop without forcing module 49allows module authors to utilise an event loop without forcing module
44users to use the same event loop (as only a single event loop can coexist 50users to use the same event loop (as only a single event loop can coexist
45peacefully at any one time). 51peacefully at any one time).
46 52
47The interface itself is vaguely similar but not identical to the Event 53The interface itself is vaguely similar but not identical to the Event
48module. 54module.
… …
62 68
63no warnings; 69no warnings;
64use strict 'vars'; 70use strict 'vars';
65use Carp; 71use Carp;
66 72
67our $VERSION = 0.3; 73our $VERSION = '1.02';
68our $MODEL; 74our $MODEL;
69 75
70our $AUTOLOAD; 76our $AUTOLOAD;
71our @ISA; 77our @ISA;
72 78
79our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
80
81our @REGISTRY;
82
73my @models = ( 83my @models = (
74 [Coro => Coro::Event::], 84 [Coro::Event:: => AnyEvent::Impl::Coro::],
75 [Event => Event::], 85 [Event:: => AnyEvent::Impl::Event::],
76 [Glib => Glib::], 86 [Glib:: => AnyEvent::Impl::Glib::],
77 [Tk => Tk::], 87 [Tk:: => AnyEvent::Impl::Tk::],
78); 88);
79 89
80our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY); 90our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);
81 91
82sub AUTOLOAD { 92sub AUTOLOAD {
… …
85 $method{$AUTOLOAD} 95 $method{$AUTOLOAD}
86 or croak "$AUTOLOAD: not a valid method for AnyEvent objects"; 96 or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
87 97
88 unless ($MODEL) { 98 unless ($MODEL) {
89 # check for already loaded models 99 # check for already loaded models
90 for (@models) { 100 for (@REGISTRY, @models) {
91 my ($model, $package) = @$_; 101 my ($package, $model) = @$_;
92 if (scalar keys %{ *{"$package\::"} }) { 102 if (${"$package\::VERSION"} > 0) {
93 eval "require AnyEvent::Impl::$model"; 103 if (eval "require $model") {
94 last if $MODEL; 104 $MODEL = $model;
105 warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
106 last;
107 }
95 } 108 }
96 } 109 }
97 110
98 unless ($MODEL) { 111 unless ($MODEL) {
99 # try to load a model 112 # try to load a model
100 113
101 for (@models) { 114 for (@REGISTRY, @models) {
102 my ($model, $package) = @$_; 115 my ($package, $model) = @$_;
103 eval "require AnyEvent::Impl::$model"; 116 if (eval "require $model") {
104 last if $MODEL; 117 $MODEL = $model;
118 warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
119 last;
120 }
105 } 121 }
106 122
107 $MODEL 123 $MODEL
108 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk."; 124 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";
109 } 125 }
… …
114 my $class = shift; 130 my $class = shift;
115 $class->$AUTOLOAD (@_); 131 $class->$AUTOLOAD (@_);
116} 132}
117 133
118=back 134=back
135
136=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
137
138If you need to support another event library which isn't directly
139supported by AnyEvent, you can supply your own interface to it by
140pushing, before the first watcher gets created, the package name of
141the event module and the package name of the interface to use onto
142C<@AnyEvent::REGISTRY>. You can do that before and even without loading
143AnyEvent.
144
145Example:
146
147 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
148
149This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
150package/class when it finds the C<urxvt> package/module is loaded. When
151AnyEvent is loaded and asked to find a suitable event model, it will
152first check for the presence of urxvt.
153
154The class should prove implementations for all watcher types (see
155L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
156(Source code) and so on for actual examples, use C<perldoc -m
157AnyEvent::Impl::Glib> to see the sources).
158
159The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
160uses the above line as-is. An interface isn't included in AnyEvent
161because it doesn't make sense outside the embedded interpreter inside
162I<rxvt-unicode>, and it is updated and maintained as part of the
163I<rxvt-unicode> distribution.
164
165I<rxvt-unicode> also cheats a bit by not providing blocking access to
166condition variables: code blocking while waiting for a condition will
167C<die>. This still works with most modules/usages, and blocking calls must
168not be in an interactive appliation, so it makes sense.
169
170=head1 ENVIRONMENT VARIABLES
171
172The following environment variables are used by this module:
173
174C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, reports which event
175model gets used.
119 176
120=head1 EXAMPLE 177=head1 EXAMPLE
121 178
122The following program uses an io watcher to read data from stdin, a timer 179The following program uses an io watcher to read data from stdin, a timer
123to display a message once per second, and a condvar to exit the program 180to display a message once per second, and a condvar to exit the program

Diff Legend

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