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

Comparing AnyEvent/README (file contents):
Revision 1.4 by root, Fri Dec 30 01:28:31 2005 UTC vs.
Revision 1.9 by root, Wed Mar 7 17:37:24 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 (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 12
26 my $w = AnyEvent->timer (after => $seconds, cb => sub { 13 my $w = AnyEvent->timer (after => $seconds, cb => sub {
27 ... 14 ...
28 }); 15 });
29 16
30 * io and time watchers get canceled whenever $w is destroyed, so keep a 17 my $w = AnyEvent->condvar; # stores wether a condition was flagged
31 copy
32
33 * timers can only be used once and must be recreated for repeated
34 operation (limitation by Glib and Tk).
35
36 my $w = AnyEvent->condvar; # kind of main loop replacement
37 $w->wait; # enters main loop till $condvar gets ->broadcast 18 $w->wait; # enters "main loop" till $condvar gets ->broadcast
38 $w->broadcast; # wake up current and all future wait's 19 $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.
44 20
45DESCRIPTION 21DESCRIPTION
46 AnyEvent provides an identical interface to multiple event loops. This 22 AnyEvent provides an identical interface to multiple event loops. This
47 allows module authors to utilizy an event loop without forcing module 23 allows module authors to utilise an event loop without forcing module
48 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
49 coexist peacefully at any one time). 25 coexist peacefully at any one time).
50 26
51 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
52 module. 28 module.
… …
54 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
55 currently loaded event loop by probing wether any of the following 31 currently loaded event loop by probing wether any of the following
56 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
57 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
58 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
59 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" teh 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. The watcher will only trigger once. This works by
166 installing a signal handler for "SIGCHLD".
167
168 Example: wait for pid 1333
169
170 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
171
172GLOBALS
173 $AnyEvent::MODEL
174 Contains "undef" until the first watcher is being created. Then it
175 contains the event model that is being used, which is the name of
176 the Perl class implementing the model. This class is usually one of
177 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*).
179
180 The known classes so far are:
181
182 AnyEvent::Impl::Coro based on Coro::Event, best choise.
183 AnyEvent::Impl::Event based on Event, also best choice :)
184 AnyEvent::Impl::Glib based on Glib, second-best choice.
185 AnyEvent::Impl::Tk based on Tk, very bad choice.
186 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
187
188 AnyEvent::detect
189 Returns $AnyEvent::MODEL, forcing autodetection of the event model
190 if necessary. You should only call this function right before you
191 would have created an AnyEvent watcher anyway, that is, very late at
192 runtime.
193
194WHAT TO DO IN A MODULE
195 As a module author, you should "use AnyEvent" and call AnyEvent methods
196 freely, but you should not load a specific event module or rely on it.
197
198 Be careful when you create watchers in the module body - Anyevent will
199 decide which event module to use as soon as the first method is called,
200 so by calling AnyEvent in your module body you force the user of your
201 module to load the event module first.
202
203WHAT TO DO IN THE MAIN PROGRAM
204 There will always be a single main program - the only place that should
205 dictate which event model to use.
206
207 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
208 do anything special and let AnyEvent decide which implementation to
209 chose.
210
211 If the main program relies on a specific event model (for example, in
212 Gtk2 programs you have to rely on either Glib or Glib::Event), you
213 should load it before loading AnyEvent or any module that uses it,
214 generally, as early as possible. The reason is that modules might create
215 watchers when they are loaded, and AnyEvent will decide on the event
216 model to use as soon as it creates watchers, and it might chose the
217 wrong one unless you load the correct one yourself.
218
219 You can chose to use a rather inefficient pure-perl implementation by
220 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is
221 generally better.
222
223SUPPLYING YOUR OWN EVENT MODEL INTERFACE
224 If you need to support another event library which isn't directly
225 supported by AnyEvent, you can supply your own interface to it by
226 pushing, before the first watcher gets created, the package name of the
227 event module and the package name of the interface to use onto
228 @AnyEvent::REGISTRY. You can do that before and even without loading
229 AnyEvent.
230
231 Example:
232
233 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
234
235 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
236 package/class when it finds the "urxvt" package/module is loaded. When
237 AnyEvent is loaded and asked to find a suitable event model, it will
238 first check for the presence of urxvt.
239
240 The class should provide implementations for all watcher types (see
241 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
242 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
243 see the sources).
244
245 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the
246 above line as-is. An interface isn't included in AnyEvent because it
247 doesn't make sense outside the embedded interpreter inside
248 *rxvt-unicode*, and it is updated and maintained as part of the
249 *rxvt-unicode* distribution.
250
251 *rxvt-unicode* also cheats a bit by not providing blocking access to
252 condition variables: code blocking while waiting for a condition will
253 "die". This still works with most modules/usages, and blocking calls
254 must not be in an interactive appliation, so it makes sense.
60 255
61ENVIRONMENT VARIABLES 256ENVIRONMENT VARIABLES
62 The following environment variables are used by this module: 257 The following environment variables are used by this module:
63 258
64 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 259 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event

Diff Legend

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