ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/README
(Generate patch)

Comparing AnyEvent/README (file contents):
Revision 1.2 by root, Thu Dec 1 21:19:58 2005 UTC vs.
Revision 1.5 by root, Sun Jan 8 04:41:08 2006 UTC

… …
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 Event, Coro, Glib, Tk - various supported event loops 4 Event, Coro, Glib, Tk - various supported event loops
5 5
6SYNOPSIS 6SYNOPSIS
7 use AnyEvent; 7 use AnyEvent;
8 8
9 my $w = AnyEvent->timer (fh => ..., poll => "[rw]+", cb => sub { 9 my $w = AnyEvent->io (fh => ..., poll => "[rw]+", cb => sub {
10 my ($poll_got) = @_; 10 my ($poll_got) = @_;
11 ... 11 ...
12 }); 12 });
13
14 * only one io watcher per $fh and $poll type is allowed (i.e. on a
15 socket you can have one r + one w or one rw watcher, not any more
16 (limitation by Tk).
17
18 * the $poll_got passed to the handler needs to be checked by looking for
19 single characters (e.g. with a regex), as it can contain more event
20 types than were requested (e.g. a 'w' watcher might generate 'rw'
21 events, limitation by Glib).
22
23 * AnyEvent will keep filehandles alive, so as long as the watcher
24 exists, the filehandle exists.
25
13 my $w = AnyEvent->io (after => $seconds, cb => sub { 26 my $w = AnyEvent->timer (after => $seconds, cb => sub {
14 ... 27 ...
15 }); 28 });
16 29
17 # watchers get canceled whenever $w is destroyed 30 * io and time watchers get canceled whenever $w is destroyed, so keep a
18 # only one watcher per $fh and $poll type is allowed 31 copy
19 # (i.e. on a socket you cna have one r + one w or one rw 32
20 # watcher, not any more. 33 * timers can only be used once and must be recreated for repeated
21 # timers can only be used once 34 operation (limitation by Glib and Tk).
22 35
23 my $w = AnyEvent->condvar; # kind of main loop replacement 36 my $w = AnyEvent->condvar; # kind of main loop replacement
24 # can only be used once
25 $w->wait; # enters main loop till $condvar gets ->send 37 $w->wait; # enters main loop till $condvar gets ->broadcast
26 $w->broadcast; # wake up waiting and future wait's 38 $w->broadcast; # wake up current and all future wait's
39
40 * condvars are used to give blocking behaviour when neccessary. Create a
41 condvar for any "request" or "event" your module might create,
42 "->broadcast" it when the event happens and provide a function that
43 calls "->wait" for it. See the examples below.
27 44
28DESCRIPTION 45DESCRIPTION
29 AnyEvent provides an identical interface to multiple event loops. This 46 AnyEvent provides an identical interface to multiple event loops. This
30 allows module authors to utilizy an event loop without forcing module 47 allows module authors to utilizy an event loop without forcing module
31 users to use the same event loop (as only a single event loop can 48 users to use the same event loop (as only a single event loop can
… …
39 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 56 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is
40 used. If none is found, the module tries to load these modules in the 57 used. If none is found, the module tries to load these modules in the
41 order given. The first one that could be successfully loaded will be 58 order given. The first one that could be successfully loaded will be
42 used. If still none could be found, it will issue an error. 59 used. If still none could be found, it will issue an error.
43 60
61SUPPLYING YOUR OWN EVENT MODEL INTERFACE
62 If you need to support another event library which isn't directly
63 supported by AnyEvent, you can supply your own interface to it by
64 pushing, before the first watch gets created, the package name of the
65 event module and the package name of the interface to use onto
66 @AnyEvent::REGISTRY. You can do that before and even without loading
67 AnyEvent.
68
69 Example:
70
71 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
72
73 This tells AnyEvent to (literally) use the "urxvt::anyevent::" module
74 when it finds the "urxvt" module is loaded. When AnyEvent is loaded and
75 requested to find a suitable event model, it will first check for the
76 urxvt module.
77
78 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the
79 above line exactly. An interface isn't included in AnyEvent because it
80 doesn't make sense outside the embedded interpreter inside
81 *rxvt-unicode*, and it is updated and maintained as part of the
82 *rxvt-unicode* distribution.
83
84ENVIRONMENT VARIABLES
85 The following environment variables are used by this module:
86
87 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
88 model gets used.
89
44EXAMPLE 90EXAMPLE
45 The following program uses an io watcher to read data from stdin, a 91 The following program uses an io watcher to read data from stdin, a
46 timer to display a message once per second, and a condvar to exit the 92 timer to display a message once per second, and a condvar to exit the
47 program when the user enters quit: 93 program when the user enters quit:
48 94
… …
68 114
69 new_timer; # create first timer 115 new_timer; # create first timer
70 116
71 $cv->wait; # wait until user enters /^q/i 117 $cv->wait; # wait until user enters /^q/i
72 118
119REAL-WORLD EXAMPLE
120 Consider the Net::FCP module. It features (among others) the following
121 API calls, which are to freenet what HTTP GET requests are to http:
122
123 my $data = $fcp->client_get ($url); # blocks
124
125 my $transaction = $fcp->txn_client_get ($url); # does not block
126 $transaction->cb ( sub { ... } ); # set optional result callback
127 my $data = $transaction->result; # possibly blocks
128
129 The "client_get" method works like "LWP::Simple::get": it requests the
130 given URL and waits till the data has arrived. It is defined to be:
131
132 sub client_get { $_[0]->txn_client_get ($_[1])->result }
133
134 And in fact is automatically generated. This is the blocking API of
135 Net::FCP, and it works as simple as in any other, similar, module.
136
137 More complicated is "txn_client_get": It only creates a transaction
138 (completion, result, ...) object and initiates the transaction.
139
140 my $txn = bless { }, Net::FCP::Txn::;
141
142 It also creates a condition variable that is used to signal the
143 completion of the request:
144
145 $txn->{finished} = AnyAvent->condvar;
146
147 It then creates a socket in non-blocking mode.
148
149 socket $txn->{fh}, ...;
150 fcntl $txn->{fh}, F_SETFL, O_NONBLOCK;
151 connect $txn->{fh}, ...
152 and !$!{EWOULDBLOCK}
153 and !$!{EINPROGRESS}
154 and Carp::croak "unable to connect: $!\n";
155
156 Then it creates a write-watcher which gets called whenever an error
157 occurs or the connection succeeds:
158
159 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
160
161 And returns this transaction object. The "fh_ready_w" callback gets
162 called as soon as the event loop detects that the socket is ready for
163 writing.
164
165 The "fh_ready_w" method makes the socket blocking again, writes the
166 request data and replaces the watcher by a read watcher (waiting for
167 reply data). The actual code is more complicated, but that doesn't
168 matter for this example:
169
170 fcntl $txn->{fh}, F_SETFL, 0;
171 syswrite $txn->{fh}, $txn->{request}
172 or die "connection or write error";
173 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
174
175 Again, "fh_ready_r" waits till all data has arrived, and then stores the
176 result and signals any possible waiters that the request ahs finished:
177
178 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
179
180 if (end-of-file or data complete) {
181 $txn->{result} = $txn->{buf};
182 $txn->{finished}->broadcast;
183 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
184 }
185
186 The "result" method, finally, just waits for the finished signal (if the
187 request was already finished, it doesn't wait, of course, and returns
188 the data:
189
190 $txn->{finished}->wait;
191 return $txn->{result};
192
193 The actual code goes further and collects all errors ("die"s,
194 exceptions) that occured during request processing. The "result" method
195 detects wether an exception as thrown (it is stored inside the $txn
196 object) and just throws the exception, which means connection errors and
197 other problems get reported tot he code that tries to use the result,
198 not in a random callback.
199
200 All of this enables the following usage styles:
201
202 1. Blocking:
203
204 my $data = $fcp->client_get ($url);
205
206 2. Blocking, but parallelizing:
207
208 my @datas = map $_->result,
209 map $fcp->txn_client_get ($_),
210 @urls;
211
212 Both blocking examples work without the module user having to know
213 anything about events.
214
215 3a. Event-based in a main program, using any support Event module:
216
217 use Event;
218
219 $fcp->txn_client_get ($url)->cb (sub {
220 my $txn = shift;
221 my $data = $txn->result;
222 ...
223 });
224
225 Event::loop;
226
227 3b. The module user could use AnyEvent, too:
228
229 use AnyEvent;
230
231 my $quit = AnyEvent->condvar;
232
233 $fcp->txn_client_get ($url)->cb (sub {
234 ...
235 $quit->broadcast;
236 });
237
238 $quit->wait;
239
73SEE ALSO 240SEE ALSO
74 Coro::Event, Coro, Event, Glib::Event, Glib, AnyEvent::Impl::Coro, 241 Event modules: Coro::Event, Coro, Event, Glib::Event, Glib.
242
243 Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event,
75 AnyEvent::Impl::Event, AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. 244 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk.
76 245
246 Nontrivial usage example: Net::FCP.
77 247
248

Diff Legend

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