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

Comparing AnyEvent/README (file contents):
Revision 1.5 by root, Sun Jan 8 04:41:08 2006 UTC vs.
Revision 1.7 by root, Fri Nov 24 14:50:12 2006 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 TIMER WATCHERS
90 You can create a timer 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
150GLOBALS
151 $AnyEvent::MODEL
152 Contains "undef" until the first watcher is being created. Then it
153 contains the event model that is being used, which is the name of
154 the Perl class implementing the model. This class is usually one of
155 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
156 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
157
158 The known classes so far are:
159
160 AnyEvent::Impl::Coro based on Coro::Event, best choise.
161 AnyEvent::Impl::Event based on Event, also best choice :)
162 AnyEvent::Impl::Glib based on Glib, second-best choice.
163 AnyEvent::Impl::Tk based on Tk, very bad choice.
164 AnyEvent::Impl::Perl pure-perl implementation, inefficient.
165
166WHAT TO DO IN A MODULE
167 As a module author, you should "use AnyEvent" and call AnyEvent methods
168 freely, but you should not load a specific event module or rely on it.
169
170 Be careful when you create watchers in the module body - Anyevent will
171 decide which event module to use as soon as the first method is called,
172 so by calling AnyEvent in your module body you force the user of your
173 module to load the event module first.
174
175WHAT TO DO IN THE MAIN PROGRAM
176 There will always be a single main program - the only place that should
177 dictate which event model to use.
178
179 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
180 do anything special and let AnyEvent decide which implementation to
181 chose.
182
183 If the main program relies on a specific event model (for example, in
184 Gtk2 programs you have to rely on either Glib or Glib::Event), you
185 should load it before loading AnyEvent or any module that uses it,
186 generally, as early as possible. The reason is that modules might create
187 watchers when they are loaded, and AnyEvent will decide on the event
188 model to use as soon as it creates watchers, and it might chose the
189 wrong one unless you load the correct one yourself.
190
191 You can chose to use a rather inefficient pure-perl implementation by
192 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is
193 generally better.
60 194
61SUPPLYING YOUR OWN EVENT MODEL INTERFACE 195SUPPLYING YOUR OWN EVENT MODEL INTERFACE
62 If you need to support another event library which isn't directly 196 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 197 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 198 pushing, before the first watcher gets created, the package name of the
65 event module and the package name of the interface to use onto 199 event module and the package name of the interface to use onto
66 @AnyEvent::REGISTRY. You can do that before and even without loading 200 @AnyEvent::REGISTRY. You can do that before and even without loading
67 AnyEvent. 201 AnyEvent.
68 202
69 Example: 203 Example:
70 204
71 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 205 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
72 206
73 This tells AnyEvent to (literally) use the "urxvt::anyevent::" module 207 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
74 when it finds the "urxvt" module is loaded. When AnyEvent is loaded and 208 package/class when it finds the "urxvt" package/module is loaded. When
75 requested to find a suitable event model, it will first check for the 209 AnyEvent is loaded and asked to find a suitable event model, it will
76 urxvt module. 210 first check for the presence of urxvt.
211
212 The class should prove implementations for all watcher types (see
213 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
214 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
215 see the sources).
77 216
78 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 217 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 218 above line as-is. An interface isn't included in AnyEvent because it
80 doesn't make sense outside the embedded interpreter inside 219 doesn't make sense outside the embedded interpreter inside
81 *rxvt-unicode*, and it is updated and maintained as part of the 220 *rxvt-unicode*, and it is updated and maintained as part of the
82 *rxvt-unicode* distribution. 221 *rxvt-unicode* distribution.
222
223 *rxvt-unicode* also cheats a bit by not providing blocking access to
224 condition variables: code blocking while waiting for a condition will
225 "die". This still works with most modules/usages, and blocking calls
226 must not be in an interactive appliation, so it makes sense.
83 227
84ENVIRONMENT VARIABLES 228ENVIRONMENT VARIABLES
85 The following environment variables are used by this module: 229 The following environment variables are used by this module:
86 230
87 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 231 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event

Diff Legend

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