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

Comparing AnyEvent/README (file contents):
Revision 1.3 by root, Sun Dec 4 09:44:32 2005 UTC vs.
Revision 1.13 by root, Fri Nov 23 10:42:00 2007 UTC

1NAME 1NAME
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, Perl - various supported event loops
5 5
6SYNOPSIS 6SYNOPSIS
7 use AnyEvent; 7 use AnyEvent;
8 8
9 my $w = AnyEvent->io (fh => ..., poll => "[rw]+", cb => sub { 9 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
10 my ($poll_got) = @_;
11 ... 10 ...
12 }); 11 });
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
17 - AnyEvent will keep filehandles alive, so as long as the watcher
18 exists, the filehandle exists.
19 12
20 my $w = AnyEvent->timer (after => $seconds, cb => sub { 13 my $w = AnyEvent->timer (after => $seconds, cb => sub {
21 ... 14 ...
22 }); 15 });
23 16
24 - io and time watchers get canceled whenever $w is destroyed, so keep a 17 my $w = AnyEvent->condvar; # stores wether a condition was flagged
25 copy
26
27 - timers can only be used once and must be recreated for repeated
28 operation
29
30 my $w = AnyEvent->condvar; # kind of main loop replacement
31 $w->wait; # enters main loop till $condvar gets ->broadcast 18 $w->wait; # enters "main loop" till $condvar gets ->broadcast
32 $w->broadcast; # wake up current and all future wait's 19 $w->broadcast; # wake up current and all future wait's
33
34 - condvars are used to give blocking behaviour when neccessary. Create a
35 condvar for any "request" or "event" your module might create,
36 "->broadcast" it when the event happens and provide a function that
37 calls "->wait" for it. See the examples below.
38 20
39DESCRIPTION 21DESCRIPTION
40 AnyEvent provides an identical interface to multiple event loops. This 22 AnyEvent provides an identical interface to multiple event loops. This
41 allows module authors to utilizy an event loop without forcing module 23 allows module authors to utilise an event loop without forcing module
42 users to use the same event loop (as only a single event loop can 24 users to use the same event loop (as only a single event loop can
43 coexist peacefully at any one time). 25 coexist peacefully at any one time).
44 26
45 The interface itself is vaguely similar but not identical to the Event 27 The interface itself is vaguely similar but not identical to the Event
46 module. 28 module.
… …
48 On the first call of any method, the module tries to detect the 30 On the first call of any method, the module tries to detect the
49 currently loaded event loop by probing wether any of the following 31 currently loaded event loop by probing wether any of the following
50 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 32 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is
51 used. If none is found, the module tries to load these modules in the 33 used. If none is found, the module tries to load these modules in the
52 order given. The first one that could be successfully loaded will be 34 order given. The first one that could be successfully loaded will be
53 used. If still none could be found, it will issue an error. 35 used. If still none could be found, AnyEvent will fall back to a
36 pure-perl event loop, which is also not very efficient.
37
38 Because AnyEvent first checks for modules that are already loaded,
39 loading an Event model explicitly before first using AnyEvent will
40 likely make that model the default. For example:
41
42 use Tk;
43 use AnyEvent;
44
45 # .. AnyEvent will likely default to Tk
46
47 The pure-perl implementation of AnyEvent is called
48 "AnyEvent::Impl::Perl". Like other event modules you can load it
49 explicitly.
50
51WATCHERS
52 AnyEvent has the central concept of a *watcher*, which is an object that
53 stores relevant data for each kind of event you are waiting for, such as
54 the callback to call, the filehandle to watch, etc.
55
56 These watchers are normal Perl objects with normal Perl lifetime. After
57 creating a watcher it will immediately "watch" for events and invoke the
58 callback. To disable the watcher you have to destroy it (e.g. by setting
59 the variable that stores it to "undef" or otherwise deleting all
60 references to it).
61
62 All watchers are created by calling a method on the "AnyEvent" class.
63
64 IO WATCHERS
65 You can create I/O watcher by calling the "AnyEvent->io" method with the
66 following mandatory arguments:
67
68 "fh" the Perl *filehandle* (not filedescriptor) to watch for events.
69 "poll" must be a string that is either "r" or "w", that creates a
70 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback
71 to invoke everytime the filehandle becomes ready.
72
73 Only one io watcher per "fh" and "poll" combination is allowed (i.e. on
74 a socket you can have one r + one w, not any more (limitation comes from
75 Tk - if you are sure you are not using Tk this limitation is gone).
76
77 Filehandles will be kept alive, so as long as the watcher exists, the
78 filehandle exists, too.
79
80 Example:
81
82 # wait for readability of STDIN, then read a line and disable the watcher
83 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
84 chomp (my $input = <STDIN>);
85 warn "read: $input\n";
86 undef $w;
87 });
88
89 TIME WATCHERS
90 You can create a time watcher by calling the "AnyEvent->timer" method
91 with the following mandatory arguments:
92
93 "after" after how many seconds (fractions are supported) should the
94 timer activate. "cb" the callback to invoke.
95
96 The timer callback will be invoked at most once: if you want a repeating
97 timer you have to create a new watcher (this is a limitation by both Tk
98 and Glib).
99
100 Example:
101
102 # fire an event after 7.7 seconds
103 my $w = AnyEvent->timer (after => 7.7, cb => sub {
104 warn "timeout\n";
105 });
106
107 # to cancel the timer:
108 undef $w;
109
110 CONDITION WATCHERS
111 Condition watchers can be created by calling the "AnyEvent->condvar"
112 method without any arguments.
113
114 A condition watcher watches for a condition - precisely that the
115 "->broadcast" method has been called.
116
117 The watcher has only two methods:
118
119 $cv->wait
120 Wait (blocking if necessary) until the "->broadcast" method has been
121 called on c<$cv>, while servicing other watchers normally.
122
123 Not all event models support a blocking wait - some die in that
124 case, so if you are using this from a module, never require a
125 blocking wait, but let the caller decide wether the call will block
126 or not (for example, by coupling condition variables with some kind
127 of request results and supporting callbacks so the caller knows that
128 getting the result will not block, while still suppporting blockign
129 waits if the caller so desires).
130
131 You can only wait once on a condition - additional calls will return
132 immediately.
133
134 $cv->broadcast
135 Flag the condition as ready - a running "->wait" and all further
136 calls to "wait" will return after this method has been called. If
137 nobody is waiting the broadcast will be remembered..
138
139 Example:
140
141 # wait till the result is ready
142 my $result_ready = AnyEvent->condvar;
143
144 # do something such as adding a timer
145 # or socket watcher the calls $result_ready->broadcast
146 # when the "result" is ready.
147
148 $result_ready->wait;
149
150 SIGNAL WATCHERS
151 You can listen for signals using a signal watcher, "signal" is the
152 signal *name* without any "SIG" prefix. Multiple signals events can be
153 clumped together into one callback invocation, and callback invocation
154 might or might not be asynchronous.
155
156 These watchers might use %SIG, so programs overwriting those signals
157 directly will likely not work correctly.
158
159 Example: exit on SIGINT
160
161 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
162
163 CHILD PROCESS WATCHERS
164 You can also listen for the status of a child process specified by the
165 "pid" argument (or any child if the pid argument is 0). The watcher will
166 trigger as often as status change for the child are received. This works
167 by installing a signal handler for "SIGCHLD". The callback will be
168 called with the pid and exit status (as returned by waitpid).
169
170 Example: wait for pid 1333
171
172 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
173
174GLOBALS
175 $AnyEvent::MODEL
176 Contains "undef" until the first watcher is being created. Then it
177 contains the event model that is being used, which is the name of
178 the Perl class implementing the model. This class is usually one of
179 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
180 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
181
182 The known classes so far are:
183
184 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
185 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
186 AnyEvent::Impl::Coro based on Coro::Event, second best choice.
187 AnyEvent::Impl::Event based on Event, also second best choice :)
188 AnyEvent::Impl::Glib based on Glib, second-best choice.
189 AnyEvent::Impl::Tk based on Tk, very bad choice.
190 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
191
192 AnyEvent::detect
193 Returns $AnyEvent::MODEL, forcing autodetection of the event model
194 if necessary. You should only call this function right before you
195 would have created an AnyEvent watcher anyway, that is, very late at
196 runtime.
197
198WHAT TO DO IN A MODULE
199 As a module author, you should "use AnyEvent" and call AnyEvent methods
200 freely, but you should not load a specific event module or rely on it.
201
202 Be careful when you create watchers in the module body - Anyevent will
203 decide which event module to use as soon as the first method is called,
204 so by calling AnyEvent in your module body you force the user of your
205 module to load the event module first.
206
207WHAT TO DO IN THE MAIN PROGRAM
208 There will always be a single main program - the only place that should
209 dictate which event model to use.
210
211 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
212 do anything special and let AnyEvent decide which implementation to
213 chose.
214
215 If the main program relies on a specific event model (for example, in
216 Gtk2 programs you have to rely on either Glib or Glib::Event), you
217 should load it before loading AnyEvent or any module that uses it,
218 generally, as early as possible. The reason is that modules might create
219 watchers when they are loaded, and AnyEvent will decide on the event
220 model to use as soon as it creates watchers, and it might chose the
221 wrong one unless you load the correct one yourself.
222
223 You can chose to use a rather inefficient pure-perl implementation by
224 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is
225 generally better.
226
227SUPPLYING YOUR OWN EVENT MODEL INTERFACE
228 If you need to support another event library which isn't directly
229 supported by AnyEvent, you can supply your own interface to it by
230 pushing, before the first watcher gets created, the package name of the
231 event module and the package name of the interface to use onto
232 @AnyEvent::REGISTRY. You can do that before and even without loading
233 AnyEvent.
234
235 Example:
236
237 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
238
239 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
240 package/class when it finds the "urxvt" package/module is loaded. When
241 AnyEvent is loaded and asked to find a suitable event model, it will
242 first check for the presence of urxvt.
243
244 The class should provide implementations for all watcher types (see
245 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
246 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
247 see the sources).
248
249 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the
250 above line as-is. An interface isn't included in AnyEvent because it
251 doesn't make sense outside the embedded interpreter inside
252 *rxvt-unicode*, and it is updated and maintained as part of the
253 *rxvt-unicode* distribution.
254
255 *rxvt-unicode* also cheats a bit by not providing blocking access to
256 condition variables: code blocking while waiting for a condition will
257 "die". This still works with most modules/usages, and blocking calls
258 must not be in an interactive application, so it makes sense.
259
260ENVIRONMENT VARIABLES
261 The following environment variables are used by this module:
262
263 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
264 model gets used.
54 265
55EXAMPLE 266EXAMPLE
56 The following program uses an io watcher to read data from stdin, a 267 The following program uses an io watcher to read data from stdin, a
57 timer to display a message once per second, and a condvar to exit the 268 timer to display a message once per second, and a condvar to exit the
58 program when the user enters quit: 269 program when the user enters quit:
… …
116 connect $txn->{fh}, ... 327 connect $txn->{fh}, ...
117 and !$!{EWOULDBLOCK} 328 and !$!{EWOULDBLOCK}
118 and !$!{EINPROGRESS} 329 and !$!{EINPROGRESS}
119 and Carp::croak "unable to connect: $!\n"; 330 and Carp::croak "unable to connect: $!\n";
120 331
121 Then it creates a write-watcher which gets called wehnever an error 332 Then it creates a write-watcher which gets called whenever an error
122 occurs or the connection succeeds: 333 occurs or the connection succeeds:
123 334
124 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w }); 335 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
125 336
126 And returns this transaction object. The "fh_ready_w" callback gets 337 And returns this transaction object. The "fh_ready_w" callback gets
… …
143 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 354 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
144 355
145 if (end-of-file or data complete) { 356 if (end-of-file or data complete) {
146 $txn->{result} = $txn->{buf}; 357 $txn->{result} = $txn->{buf};
147 $txn->{finished}->broadcast; 358 $txn->{finished}->broadcast;
359 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
148 } 360 }
149 361
150 The "result" method, finally, just waits for the finished signal (if the 362 The "result" method, finally, just waits for the finished signal (if the
151 request was already finished, it doesn't wait, of course, and returns 363 request was already finished, it doesn't wait, of course, and returns
152 the data: 364 the data:
153 365
154 $txn->{finished}->wait; 366 $txn->{finished}->wait;
155 return $txn->{buf}; 367 return $txn->{result};
156 368
157 The actual code goes further and collects all errors ("die"s, 369 The actual code goes further and collects all errors ("die"s,
158 exceptions) that occured during request processing. The "result" method 370 exceptions) that occured during request processing. The "result" method
159 detects wether an exception as thrown (it is stored inside the $txn 371 detects wether an exception as thrown (it is stored inside the $txn
160 object) and just throws the exception, which means connection errors and 372 object) and just throws the exception, which means connection errors and

Diff Legend

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