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.6 by root, Wed Nov 1 01:22:19 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
150WHAT TO DO IN A MODULE
151 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.
153
154 Be careful when you create watchers in the module body - Anyevent will
155 decide which event module to use as soon as the first method is called,
156 so by calling AnyEvent in your module body you force the user of your
157 module to load the event module first.
158
159WHAT TO DO IN THE MAIN PROGRAM
160 There will always be a single main program - the only place that should
161 dictate which event model to use.
162
163 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
164 do anything special and let AnyEvent decide which implementation to
165 chose.
166
167 If the main program relies on a specific event model (for example, in
168 Gtk2 programs you have to rely on either Glib or Glib::Event), you
169 should load it before loading AnyEvent or any module that uses it,
170 generally, as early as possible. The reason is that modules might create
171 watchers when they are loaded, and AnyEvent will decide on the event
172 model to use as soon as it creates watchers, and it might chose the
173 wrong one unless you load the correct one yourself.
174
175 You can chose to use a rather inefficient pure-perl implementation by
176 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is
177 generally better.
60 178
61SUPPLYING YOUR OWN EVENT MODEL INTERFACE 179SUPPLYING YOUR OWN EVENT MODEL INTERFACE
62 If you need to support another event library which isn't directly 180 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 181 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 182 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 183 event module and the package name of the interface to use onto
66 @AnyEvent::REGISTRY. You can do that before and even without loading 184 @AnyEvent::REGISTRY. You can do that before and even without loading
67 AnyEvent. 185 AnyEvent.
68 186
69 Example: 187 Example:
70 188
71 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 189 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
72 190
73 This tells AnyEvent to (literally) use the "urxvt::anyevent::" module 191 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
74 when it finds the "urxvt" module is loaded. When AnyEvent is loaded and 192 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 193 AnyEvent is loaded and asked to find a suitable event model, it will
76 urxvt module. 194 first check for the presence of urxvt.
195
196 The class should prove implementations for all watcher types (see
197 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code)
198 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to
199 see the sources).
77 200
78 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 201 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 202 above line as-is. An interface isn't included in AnyEvent because it
80 doesn't make sense outside the embedded interpreter inside 203 doesn't make sense outside the embedded interpreter inside
81 *rxvt-unicode*, and it is updated and maintained as part of the 204 *rxvt-unicode*, and it is updated and maintained as part of the
82 *rxvt-unicode* distribution. 205 *rxvt-unicode* distribution.
206
207 *rxvt-unicode* also cheats a bit by not providing blocking access to
208 condition variables: code blocking while waiting for a condition will
209 "die". This still works with most modules/usages, and blocking calls
210 must not be in an interactive appliation, so it makes sense.
83 211
84ENVIRONMENT VARIABLES 212ENVIRONMENT VARIABLES
85 The following environment variables are used by this module: 213 The following environment variables are used by this module:
86 214
87 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 215 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event

Diff Legend

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