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

Comparing AnyEvent/README (file contents):
Revision 1.3 by root, Sun Dec 4 09:44:32 2005 UTC vs.
Revision 1.5 by root, Sun Jan 8 04:41:08 2006 UTC

… …
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 - 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 => ..., poll => "[rw]+", cb => sub {
10 my ($poll_got) = @_; 10 my ($poll_got) = @_;
11 ... 11 ...
12 }); 12 });
13 13
14 - only one io watcher per $fh and $poll type is allowed (i.e. on a 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. 15 socket you can have one r + one w or one rw watcher, not any more
16 (limitation by Tk).
16 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
17 - AnyEvent will keep filehandles alive, so as long as the watcher 23 * AnyEvent will keep filehandles alive, so as long as the watcher
18 exists, the filehandle exists. 24 exists, the filehandle exists.
19 25
20 my $w = AnyEvent->timer (after => $seconds, cb => sub { 26 my $w = AnyEvent->timer (after => $seconds, cb => sub {
21 ... 27 ...
22 }); 28 });
23 29
24 - io and time watchers get canceled whenever $w is destroyed, so keep a 30 * io and time watchers get canceled whenever $w is destroyed, so keep a
25 copy 31 copy
26 32
27 - timers can only be used once and must be recreated for repeated 33 * timers can only be used once and must be recreated for repeated
28 operation 34 operation (limitation by Glib and Tk).
29 35
30 my $w = AnyEvent->condvar; # kind of main loop replacement 36 my $w = AnyEvent->condvar; # kind of main loop replacement
31 $w->wait; # enters main loop till $condvar gets ->broadcast 37 $w->wait; # enters main loop till $condvar gets ->broadcast
32 $w->broadcast; # wake up current and all future wait's 38 $w->broadcast; # wake up current and all future wait's
33 39
34 - condvars are used to give blocking behaviour when neccessary. Create a 40 * condvars are used to give blocking behaviour when neccessary. Create a
35 condvar for any "request" or "event" your module might create, 41 condvar for any "request" or "event" your module might create,
36 "->broadcast" it when the event happens and provide a function that 42 "->broadcast" it when the event happens and provide a function that
37 calls "->wait" for it. See the examples below. 43 calls "->wait" for it. See the examples below.
38 44
39DESCRIPTION 45DESCRIPTION
… …
50 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 56 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is
51 used. If none is found, the module tries to load these modules in the 57 used. If none is found, the module tries to load these modules in the
52 order given. The first one that could be successfully loaded will be 58 order given. The first one that could be successfully loaded will be
53 used. If still none could be found, it will issue an error. 59 used. If still none could be found, it will issue an error.
54 60
61SUPPLYING YOUR OWN EVENT MODEL INTERFACE
62 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
64 pushing, before the first watch gets created, the package name of the
65 event module and the package name of the interface to use onto
66 @AnyEvent::REGISTRY. You can do that before and even without loading
67 AnyEvent.
68
69 Example:
70
71 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
72
73 This tells AnyEvent to (literally) use the "urxvt::anyevent::" module
74 when it finds the "urxvt" module is loaded. When AnyEvent is loaded and
75 requested to find a suitable event model, it will first check for the
76 urxvt module.
77
78 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
80 doesn't make sense outside the embedded interpreter inside
81 *rxvt-unicode*, and it is updated and maintained as part of the
82 *rxvt-unicode* distribution.
83
84ENVIRONMENT VARIABLES
85 The following environment variables are used by this module:
86
87 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
88 model gets used.
89
55EXAMPLE 90EXAMPLE
56 The following program uses an io watcher to read data from stdin, a 91 The following program uses an io watcher to read data from stdin, a
57 timer to display a message once per second, and a condvar to exit the 92 timer to display a message once per second, and a condvar to exit the
58 program when the user enters quit: 93 program when the user enters quit:
59 94
… …
116 connect $txn->{fh}, ... 151 connect $txn->{fh}, ...
117 and !$!{EWOULDBLOCK} 152 and !$!{EWOULDBLOCK}
118 and !$!{EINPROGRESS} 153 and !$!{EINPROGRESS}
119 and Carp::croak "unable to connect: $!\n"; 154 and Carp::croak "unable to connect: $!\n";
120 155
121 Then it creates a write-watcher which gets called wehnever an error 156 Then it creates a write-watcher which gets called whenever an error
122 occurs or the connection succeeds: 157 occurs or the connection succeeds:
123 158
124 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w }); 159 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
125 160
126 And returns this transaction object. The "fh_ready_w" callback gets 161 And returns this transaction object. The "fh_ready_w" callback gets
… …
143 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 178 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
144 179
145 if (end-of-file or data complete) { 180 if (end-of-file or data complete) {
146 $txn->{result} = $txn->{buf}; 181 $txn->{result} = $txn->{buf};
147 $txn->{finished}->broadcast; 182 $txn->{finished}->broadcast;
183 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
148 } 184 }
149 185
150 The "result" method, finally, just waits for the finished signal (if the 186 The "result" method, finally, just waits for the finished signal (if the
151 request was already finished, it doesn't wait, of course, and returns 187 request was already finished, it doesn't wait, of course, and returns
152 the data: 188 the data:
153 189
154 $txn->{finished}->wait; 190 $txn->{finished}->wait;
155 return $txn->{buf}; 191 return $txn->{result};
156 192
157 The actual code goes further and collects all errors ("die"s, 193 The actual code goes further and collects all errors ("die"s,
158 exceptions) that occured during request processing. The "result" method 194 exceptions) that occured during request processing. The "result" method
159 detects wether an exception as thrown (it is stored inside the $txn 195 detects wether an exception as thrown (it is stored inside the $txn
160 object) and just throws the exception, which means connection errors and 196 object) and just throws the exception, which means connection errors and

Diff Legend

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