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

Comparing AnyEvent/README (file contents):
Revision 1.10 by root, Mon Jul 16 19:36:36 2007 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).
… …
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
… …
160 208
161 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 209 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
162 210
163 CHILD PROCESS WATCHERS 211 CHILD PROCESS WATCHERS
164 You can also listen for the status of a child process specified by the 212 You can also listen for the status of a child process specified by the
165 "pid" argument. The watcher will only trigger once. This works by 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
166 installing a signal handler for "SIGCHLD". 215 by installing a signal handler for "SIGCHLD". The callback will be
216 called with the pid and exit status (as returned by waitpid).
167 217
168 Example: wait for pid 1333 218 Example: wait for pid 1333
169 219
170 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 220 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
171 221
… …
177 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 227 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
178 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 228 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
179 229
180 The known classes so far are: 230 The known classes so far are:
181 231
182 AnyEvent::Impl::Coro based on Coro::Event, best choise. 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.
183 AnyEvent::Impl::Event based on Event, also best choice :) 235 AnyEvent::Impl::Event based on Event, also second best choice :)
184 AnyEvent::Impl::Glib based on Glib, second-best choice. 236 AnyEvent::Impl::Glib based on Glib, second-best choice.
185 AnyEvent::Impl::Tk based on Tk, very bad choice. 237 AnyEvent::Impl::Tk based on Tk, very bad choice.
186 AnyEvent::Impl::Perl pure-perl implementation, inefficient. 238 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
187 239
188 AnyEvent::detect 240 AnyEvent::detect

Diff Legend

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