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

Comparing AnyEvent/README (file contents):
Revision 1.6 by root, Wed Nov 1 01:22:19 2006 UTC vs.
Revision 1.14 by root, Mon Apr 7 19:46:50 2008 UTC

… …
15 }); 15 });
16 16
17 my $w = AnyEvent->condvar; # stores wether a condition was flagged 17 my $w = AnyEvent->condvar; # stores wether a condition was flagged
18 $w->wait; # enters "main loop" till $condvar gets ->broadcast 18 $w->wait; # enters "main loop" till $condvar gets ->broadcast
19 $w->broadcast; # wake up current and all future wait's 19 $w->broadcast; # wake up current and all future wait's
20
21WHY YOU SHOULD USE THIS MODULE (OR NOT)
22 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
23 nowadays. So what is different about AnyEvent?
24
25 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
26 policy* and AnyEvent is *small and efficient*.
27
28 First and foremost, *AnyEvent is not an event model* itself, it only
29 interfaces to whatever event model the main program happens to use in a
30 pragmatic way. For event models and certain classes of immortals alike,
31 the statement "there can only be one" is a bitter reality, and AnyEvent
32 helps hiding the differences.
33
34 The goal of AnyEvent is to offer module authors the ability to do event
35 programming (waiting for I/O or timer events) without subscribing to a
36 religion, a way of living, and most importantly: without forcing your
37 module users into the same thing by forcing them to use the same event
38 model you use.
39
40 For modules like POE or IO::Async (which is actually doing all I/O
41 *synchronously*...), using them in your module is like joining a cult:
42 After you joined, you are dependent on them and you cannot use anything
43 else, as it is simply incompatible to everything that isn't itself.
44
45 AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
46 works fine etc. etc. but none of these work together with the rest: POE
47 + IO::Async? no go. Tk + Event? no go. If your module uses one of those,
48 every user of your module has to use it, too. If your module uses
49 AnyEvent, it works transparently with all event models it supports
50 (including stuff like POE and IO::Async).
51
52 In addition of being free of having to use *the one and only true event
53 model*, AnyEvent also is free of bloat and policy: with POE or similar
54 modules, you get an enourmous amount of code and strict rules you have
55 to follow. AnyEvent, on the other hand, is lean and to the point by only
56 offering the functionality that is useful, in as thin as a wrapper as
57 technically possible.
58
59 Of course, if you want lots of policy (this can arguably be somewhat
60 useful) and you want to force your users to use the one and only event
61 model, you should *not* use this module.
20 62
21DESCRIPTION 63DESCRIPTION
22 AnyEvent provides an identical interface to multiple event loops. This 64 AnyEvent provides an identical interface to multiple event loops. This
23 allows module authors to utilise an event loop without forcing module 65 allows module authors to utilise an event loop without forcing module
24 users to use the same event loop (as only a single event loop can 66 users to use the same event loop (as only a single event loop can
… …
65 You can create I/O watcher by calling the "AnyEvent->io" method with the 107 You can create I/O watcher by calling the "AnyEvent->io" method with the
66 following mandatory arguments: 108 following mandatory arguments:
67 109
68 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 110 "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 111 "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" teh callback 112 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback
71 to invoke everytime the filehandle becomes ready. 113 to invoke everytime the filehandle becomes ready.
72 114
73 Only one io watcher per "fh" and "poll" combination is allowed (i.e. on 115 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 116 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). 117 Tk - if you are sure you are not using Tk this limitation is gone).
… …
84 chomp (my $input = <STDIN>); 126 chomp (my $input = <STDIN>);
85 warn "read: $input\n"; 127 warn "read: $input\n";
86 undef $w; 128 undef $w;
87 }); 129 });
88 130
89 TIMER WATCHERS 131 TIME WATCHERS
90 You can create a timer watcher by calling the "AnyEvent->timer" method 132 You can create a time watcher by calling the "AnyEvent->timer" method
91 with the following mandatory arguments: 133 with the following mandatory arguments:
92 134
93 "after" after how many seconds (fractions are supported) should the 135 "after" after how many seconds (fractions are supported) should the
94 timer activate. "cb" the callback to invoke. 136 timer activate. "cb" the callback to invoke.
95 137
… …
103 my $w = AnyEvent->timer (after => 7.7, cb => sub { 145 my $w = AnyEvent->timer (after => 7.7, cb => sub {
104 warn "timeout\n"; 146 warn "timeout\n";
105 }); 147 });
106 148
107 # to cancel the timer: 149 # to cancel the timer:
108 undef $w 150 undef $w;
109 151
110 CONDITION WATCHERS 152 CONDITION WATCHERS
111 Condition watchers can be created by calling the "AnyEvent->condvar" 153 Condition watchers can be created by calling the "AnyEvent->condvar"
112 method without any arguments. 154 method without any arguments.
113 155
114 A condition watcher watches for a condition - precisely that the 156 A condition watcher watches for a condition - precisely that the
115 "->broadcast" method has been called. 157 "->broadcast" method has been called.
158
159 Note that condition watchers recurse into the event loop - if you have
160 two watchers that call "->wait" in a round-robbin fashion, you lose.
161 Therefore, condition watchers are good to export to your caller, but you
162 should avoid making a blocking wait, at least in callbacks, as this
163 usually asks for trouble.
116 164
117 The watcher has only two methods: 165 The watcher has only two methods:
118 166
119 $cv->wait 167 $cv->wait
120 Wait (blocking if necessary) until the "->broadcast" method has been 168 Wait (blocking if necessary) until the "->broadcast" method has been
… …
145 # or socket watcher the calls $result_ready->broadcast 193 # or socket watcher the calls $result_ready->broadcast
146 # when the "result" is ready. 194 # when the "result" is ready.
147 195
148 $result_ready->wait; 196 $result_ready->wait;
149 197
198 SIGNAL WATCHERS
199 You can listen for signals using a signal watcher, "signal" is the
200 signal *name* without any "SIG" prefix. Multiple signals events can be
201 clumped together into one callback invocation, and callback invocation
202 might or might not be asynchronous.
203
204 These watchers might use %SIG, so programs overwriting those signals
205 directly will likely not work correctly.
206
207 Example: exit on SIGINT
208
209 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
210
211 CHILD PROCESS WATCHERS
212 You can also listen for the status of a child process specified by the
213 "pid" argument (or any child if the pid argument is 0). The watcher will
214 trigger as often as status change for the child are received. This works
215 by installing a signal handler for "SIGCHLD". The callback will be
216 called with the pid and exit status (as returned by waitpid).
217
218 Example: wait for pid 1333
219
220 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
221
222GLOBALS
223 $AnyEvent::MODEL
224 Contains "undef" until the first watcher is being created. Then it
225 contains the event model that is being used, which is the name of
226 the Perl class implementing the model. This class is usually one of
227 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
228 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
229
230 The known classes so far are:
231
232 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
233 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
234 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
235 AnyEvent::Impl::Event based on Event, also second best choice :)
236 AnyEvent::Impl::Glib based on Glib, second-best choice.
237 AnyEvent::Impl::Tk based on Tk, very bad choice.
238 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
239
240 AnyEvent::detect
241 Returns $AnyEvent::MODEL, forcing autodetection of the event model
242 if necessary. You should only call this function right before you
243 would have created an AnyEvent watcher anyway, that is, very late at
244 runtime.
245
150WHAT TO DO IN A MODULE 246WHAT TO DO IN A MODULE
151 As a module author, you should "use AnyEvent" and call AnyEvent methods 247 As a module author, you should "use AnyEvent" and call AnyEvent methods
152 freely, but you should not load a specific event module or rely on it. 248 freely, but you should not load a specific event module or rely on it.
153 249
154 Be careful when you create watchers in the module body - Anyevent will 250 Be careful when you create watchers in the module body - Anyevent will
… …
191 This tells AnyEvent to (literally) use the "urxvt::anyevent::" 287 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
192 package/class when it finds the "urxvt" package/module is loaded. When 288 package/class when it finds the "urxvt" package/module is loaded. When
193 AnyEvent is loaded and asked to find a suitable event model, it will 289 AnyEvent is loaded and asked to find a suitable event model, it will
194 first check for the presence of urxvt. 290 first check for the presence of urxvt.
195 291
196 The class should prove implementations for all watcher types (see 292 The class should provide implementations for all watcher types (see
197 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code) 293 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
198 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to 294 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
199 see the sources). 295 see the sources).
200 296
201 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 297 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the
… …
205 *rxvt-unicode* distribution. 301 *rxvt-unicode* distribution.
206 302
207 *rxvt-unicode* also cheats a bit by not providing blocking access to 303 *rxvt-unicode* also cheats a bit by not providing blocking access to
208 condition variables: code blocking while waiting for a condition will 304 condition variables: code blocking while waiting for a condition will
209 "die". This still works with most modules/usages, and blocking calls 305 "die". This still works with most modules/usages, and blocking calls
210 must not be in an interactive appliation, so it makes sense. 306 must not be in an interactive application, so it makes sense.
211 307
212ENVIRONMENT VARIABLES 308ENVIRONMENT VARIABLES
213 The following environment variables are used by this module: 309 The following environment variables are used by this module:
214 310
215 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 311 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event

Diff Legend

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