ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV-Loop-Async/Async.pm
(Generate patch)

Comparing EV-Loop-Async/Async.pm (file contents):
Revision 1.2 by root, Tue Jul 14 13:24:34 2009 UTC vs.
Revision 1.9 by root, Mon Nov 1 22:28:41 2010 UTC

… …
8 8
9 my $loop = EV::Loop::Async::default; 9 my $loop = EV::Loop::Async::default;
10 my $timer; 10 my $timer;
11 my $flag; 11 my $flag;
12 12
13 # create a watcher, but make sure the loop is locked
13 { 14 {
14 $loop->scope_lock; # lock the loop structures 15 $loop->scope_lock; # lock the loop structures
15 $timer = $loop->timer (5, 1, sub { $flag = 1 }); 16 $timer = $loop->timer (5, 1, sub { $flag = 1 });
16 $loop->nudge; # tell loop to take note of the timer 17 $loop->notify; # tell loop to take note of the timer
17 } 18 }
18 19
19 1 while $flag; # $flag will be set asynchronously 20 1 while $flag; # $flag will be set asynchronously
20 21
22 # implement a critical section, uninterrupted by any callbacks
21 { 23 {
22 $loop->interrupt->scope_block; 24 $loop->interrupt->scope_block;
23 # critical section, no watcher callback interruptions 25 # critical section, no watcher callback interruptions
24 } 26 }
25 27
26 # stop timer again 28 # stop the timer watcher again - locking is required once more
27
28 { 29 {
29 $loop->scope_lock; # lock the loop structures 30 $loop->scope_lock; # lock the loop structures
30 $timer->stop; 31 $timer->stop;
31 # no need to nudge 32 # no need to notify
32 } 33 }
33 34
34=head1 DESCRIPTION 35=head1 DESCRIPTION
35 36
36This module implements a rather specialised event loop - it takes a normal 37This module implements a rather specialised event loop - it takes a normal
… …
46your perl program can be interrupted (and how to avoid it), and how to 47your perl program can be interrupted (and how to avoid it), and how to
47integrate background event loops into foreground ones. 48integrate background event loops into foreground ones.
48 49
49=head1 FAQ 50=head1 FAQ
50 51
52=over 4
53
54=item Why on earth...???
55
56Sometimes you need lower latency for specific events, but it's too heavy
57to continuously poll for events. And perl already does this for you
58anyways, so this module only uses this existing mechanism.
59
60=item When do I have to lock?
61
62When in doubt, lock. Do not start or stop a watcher, do not create a
63watcher (unless with the C<_ns> methods) and do not DESTROY an active
64watcher without locking either.
65
66Any other event loop modifications need to be done while locked as
67well. So when in doubt, lock (best using C<scope_lock>).
68
69=item Why explicit locking?
70
71Because I was too lazy to wrap everything and there are probably only a
72few people on this world using this module.
73
74=back
75
51=head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE 76=head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE
52 77
53=over 4 78=over 4
54 79
55=cut 80=cut
… …
62use Async::Interrupt (); 87use Async::Interrupt ();
63 88
64use base 'EV::Loop'; 89use base 'EV::Loop';
65 90
66BEGIN { 91BEGIN {
67 our $VERSION = '0.02'; 92 our $VERSION = '1.01';
68 93
69 require XSLoader; 94 require XSLoader;
70 XSLoader::load ("EV::Loop::Async", $VERSION); 95 XSLoader::load ("EV::Loop::Async", $VERSION);
71} 96}
72 97
… …
108 $EV::Loop::Async::INTERRUPT->scope_block; 133 $EV::Loop::Async::INTERRUPT->scope_block;
109 # no default loop callbacks will be executed here. 134 # no default loop callbacks will be executed here.
110 # the loop will not be locked, however. 135 # the loop will not be locked, however.
111 } 136 }
112 137
138Example: embed the default EV::Async::Loop loop into the default L<EV>
139loop (note that it could be any other event loop as well).
140
141 my $async_w = EV::io
142 $EV::Loop::Async::LOOP->interrupt->pipe_fileno,
143 EV::READ,
144 sub { };
145
113=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...] 146=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
114 147
115This constructor: 148This constructor:
116 149
117=over 4 150=over 4
… …
125=item 4. runs C<< $loop->run >> in that thread. 158=item 4. runs C<< $loop->run >> in that thread.
126 159
127=back 160=back
128 161
129The resulting loop will be running and unlocked when it is returned. 162The resulting loop will be running and unlocked when it is returned.
163
164Example: create a new loop, block it's interrupt object and embed
165it into the foreground L<AnyEvent> event loop. This basically runs the
166C<EV::Loop::Async> loop in a synchronous way inside another loop.
167
168 my $loop = new EV::Loop::Async 0;
169 my $async = $loop->interrupt;
170
171 $async->block;
172
173 my $async_w = AnyEvent->io (
174 fh => $async->pipe_fileno,
175 poll => "r",
176 cb => sub {
177 # temporarily unblock to handle events
178 $async->unblock;
179 $async->block;
180 },
181 );
130 182
131=cut 183=cut
132 184
133sub new { 185sub new {
134 my ($class, $flags, @asy) = @_; 186 my ($class, $flags, @asy) = @_;
135 187
136 my $self = bless $class->SUPER::new ($flags), $class; 188 my $self = bless $class->SUPER::new ($flags), $class;
137 my ($c_func, $c_arg) = _c_func $self; 189 my ($c_func, $c_arg) = _c_func $self;
138 my $asy = new Async::Interrupt @asy, c_cb => [$c_func, $c_arg]; 190 my $asy = new Async::Interrupt @asy, c_cb => [$c_func, $c_arg];
139 $self->_attach ($asy, $asy->signal_func); 191 _attach $self, $asy, $asy->signal_func;
140 192
141 $self 193 $self
142} 194}
143 195
144=item $loop->nudge 196=item $loop->notify
145 197
146Wake up the asynchronous loop. This is useful after registering a new 198Wake up the asynchronous loop. This is useful after registering a new
147watcher, to ensure that the background event loop integrates the new 199watcher, to ensure that the background event loop integrates the new
148watcher(s) (which only happens when it iterates, which you can force by 200watcher(s) (which only happens when it iterates, which you can force by
149calling this method). 201calling this method).
150 202
151Without calling this method, the event loop I<eventually> takes notice 203Without calling this method, the event loop I<eventually> takes notice
152of new watchers, bit when this happens is not wlel-defined (can be 204of new watchers, bit when this happens is not well-defined (can be
153instantaneous, or take a few hours). 205instantaneous, or take a few hours).
154 206
155No locking is required. 207No locking is required.
156 208
157Example: lock the loop, create a timer, nudge the loop so it takes notice 209Example: lock the loop, create a timer, nudge the loop so it takes notice
… …
161 my $flag; 213 my $flag;
162 214
163 { 215 {
164 $loop->scope_lock; 216 $loop->scope_lock;
165 $timer = $loop->timer (1, 0, sub { $flag = 1 }); 217 $timer = $loop->timer (1, 0, sub { $flag = 1 });
166 $loop->nudge; 218 $loop->notify;
167 } 219 }
168 220
169 1 until $flag; 221 1 until $flag;
170 222
171=item $loop->lock 223=item $loop->lock
… …
192=item $loop->scope_lock 244=item $loop->scope_lock
193 245
194Calls C<lock> immediately, and C<unlock> automatically whent he current 246Calls C<lock> immediately, and C<unlock> automatically whent he current
195scope is left. 247scope is left.
196 248
249=item $loop->set_max_foreground_loops ($max_loops)
250
251The background loop will immediately stop polling for new events after it
252has collected at least one new event, regardless of how long it then takes
253to actually handle them.
254
255When Perl finally handles the events, there could be many more ready
256file descriptors. To improve latency and performance, you can ask
257C<EV::Loop::Async> to loop an additional number of times in the foreground
258after invoking the callbacks, effectively doing the polling in the
259foreground.
260
261The default is C<0>, meaning that no foreground polling will be done. A
262value of C<1> means that, after handling the pending events, it will call
263C<< $loop->loop (EV::LOOP_NONBLOCK) >> and handle the resulting events, if
264any. A value of C<2> means that this will be iterated twice.
265
266When a foreground event poll does not yield any new events, then no
267further iterations will be made, so this is only a I<maximum> value of
268additional loop runs.
269
270Take also note of the standard EV C<set_io_collect_interval>
271functionality, which can achieve a similar, but different, effect - YMMV.
272
197=back 273=back
198 274
199=head1 SEE ALSO 275=head1 SEE ALSO
200 276
201L<EV>, L<Async::Interrupt>. 277L<EV>, L<Async::Interrupt>.

Diff Legend

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