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.4 by root, Fri Dec 30 01:28:31 2005 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
61ENVIRONMENT VARIABLES
62 The following environment variables are used by this module:
63
64 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
65 model gets used.
66
55EXAMPLE 67EXAMPLE
56 The following program uses an io watcher to read data from stdin, a 68 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 69 timer to display a message once per second, and a condvar to exit the
58 program when the user enters quit: 70 program when the user enters quit:
59 71
… …
116 connect $txn->{fh}, ... 128 connect $txn->{fh}, ...
117 and !$!{EWOULDBLOCK} 129 and !$!{EWOULDBLOCK}
118 and !$!{EINPROGRESS} 130 and !$!{EINPROGRESS}
119 and Carp::croak "unable to connect: $!\n"; 131 and Carp::croak "unable to connect: $!\n";
120 132
121 Then it creates a write-watcher which gets called wehnever an error 133 Then it creates a write-watcher which gets called whenever an error
122 occurs or the connection succeeds: 134 occurs or the connection succeeds:
123 135
124 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w }); 136 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
125 137
126 And returns this transaction object. The "fh_ready_w" callback gets 138 And returns this transaction object. The "fh_ready_w" callback gets
… …
143 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 155 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
144 156
145 if (end-of-file or data complete) { 157 if (end-of-file or data complete) {
146 $txn->{result} = $txn->{buf}; 158 $txn->{result} = $txn->{buf};
147 $txn->{finished}->broadcast; 159 $txn->{finished}->broadcast;
160 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
148 } 161 }
149 162
150 The "result" method, finally, just waits for the finished signal (if the 163 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 164 request was already finished, it doesn't wait, of course, and returns
152 the data: 165 the data:
153 166
154 $txn->{finished}->wait; 167 $txn->{finished}->wait;
155 return $txn->{buf}; 168 return $txn->{result};
156 169
157 The actual code goes further and collects all errors ("die"s, 170 The actual code goes further and collects all errors ("die"s,
158 exceptions) that occured during request processing. The "result" method 171 exceptions) that occured during request processing. The "result" method
159 detects wether an exception as thrown (it is stored inside the $txn 172 detects wether an exception as thrown (it is stored inside the $txn
160 object) and just throws the exception, which means connection errors and 173 object) and just throws the exception, which means connection errors and

Diff Legend

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