… | |
… | |
2 | |
2 | |
3 | EV::Loop::Async - run an EV event loop asynchronously |
3 | EV::Loop::Async - run an EV event loop asynchronously |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | use EV::Loop::Async; |
7 | use EV::Loop::Async; |
|
|
8 | |
|
|
9 | my $loop = EV::Loop::Async::default; |
|
|
10 | my $timer; |
|
|
11 | my $flag; |
|
|
12 | |
|
|
13 | # create a watcher, but make sure the loop is locked |
|
|
14 | { |
|
|
15 | $loop->scope_lock; # lock the loop structures |
|
|
16 | $timer = $loop->timer (5, 1, sub { $flag = 1 }); |
|
|
17 | $loop->notify; # tell loop to take note of the timer |
|
|
18 | } |
|
|
19 | |
|
|
20 | 1 while $flag; # $flag will be set asynchronously |
|
|
21 | |
|
|
22 | # implement a critical section, uninterrupted by any callbacks |
|
|
23 | { |
|
|
24 | $loop->interrupt->scope_block; |
|
|
25 | # critical section, no watcher callback interruptions |
|
|
26 | } |
|
|
27 | |
|
|
28 | # stop the timer watcher again - locking is required once more |
|
|
29 | { |
|
|
30 | $loop->scope_lock; # lock the loop structures |
|
|
31 | $timer->stop; |
|
|
32 | # no need to notify |
|
|
33 | } |
8 | |
34 | |
9 | =head1 DESCRIPTION |
35 | =head1 DESCRIPTION |
10 | |
36 | |
11 | TODO. |
37 | This module implements a rather specialised event loop - it takes a normal |
|
|
38 | L<EV> event loop and runs it in a separate thread. That means it will poll |
|
|
39 | for events even while your foreground Perl interpreter is busy (you don't |
|
|
40 | need to have perls pseudo-threads enabled for this either). |
|
|
41 | |
|
|
42 | Whenever the event loop detecs new events, it will interrupt perl and ask |
|
|
43 | it to invoke all the pending watcher callbacks. This invocation will be |
|
|
44 | "synchronous" (in the perl thread), but it can happen at any time. |
|
|
45 | |
|
|
46 | See the documentation for L<Async::Interrupt> for details on when and how |
|
|
47 | your perl program can be interrupted (and how to avoid it), and how to |
|
|
48 | integrate background event loops into foreground ones. |
|
|
49 | |
|
|
50 | =head1 FAQ |
|
|
51 | |
|
|
52 | =over 4 |
|
|
53 | |
|
|
54 | =item Why on earth...??? |
|
|
55 | |
|
|
56 | Sometimes you need lower latency for specific events, but it's too heavy |
|
|
57 | to continuously poll for events. And perl already does this for you |
|
|
58 | anyways, so this module only uses this existing mechanism. |
|
|
59 | |
|
|
60 | =item When do I have to lock? |
|
|
61 | |
|
|
62 | When in doubt, lock. Do not start or stop a watcher, do not create a |
|
|
63 | watcher (unless with the C<_ns> methods) and do not DESTROY an active |
|
|
64 | watcher without locking either. |
|
|
65 | |
|
|
66 | Any other event loop modifications need to be done while locked as |
|
|
67 | well. So when in doubt, lock (best using C<scope_lock>). |
|
|
68 | |
|
|
69 | =item Why explicit locking? |
|
|
70 | |
|
|
71 | Because I was too lazy to wrap everything and there are probably only a |
|
|
72 | few people on this world using this module. |
|
|
73 | |
|
|
74 | =back |
|
|
75 | |
|
|
76 | =head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE |
12 | |
77 | |
13 | =over 4 |
78 | =over 4 |
14 | |
79 | |
15 | =cut |
80 | =cut |
16 | |
81 | |
… | |
… | |
22 | use Async::Interrupt (); |
87 | use Async::Interrupt (); |
23 | |
88 | |
24 | use base 'EV::Loop'; |
89 | use base 'EV::Loop'; |
25 | |
90 | |
26 | BEGIN { |
91 | BEGIN { |
27 | our $VERSION = '0.02'; |
92 | our $VERSION = '0.04'; |
28 | |
93 | |
29 | require XSLoader; |
94 | require XSLoader; |
30 | XSLoader::load ("EV::Loop::Async", $VERSION); |
95 | XSLoader::load ("EV::Loop::Async", $VERSION); |
31 | } |
96 | } |
32 | |
97 | |
… | |
… | |
34 | |
99 | |
35 | Return the default loop, usable by all programs. The default loop will be |
100 | Return the default loop, usable by all programs. The default loop will be |
36 | created on the first call to C<default> by calling X<new EV::Loop>, and |
101 | created on the first call to C<default> by calling X<new EV::Loop>, and |
37 | should be used by all programs unless they have special requirements. |
102 | should be used by all programs unless they have special requirements. |
38 | |
103 | |
39 | =cut |
104 | The associated L<Async::Interrupt> object is stored in |
|
|
105 | C<$EV::Loop::Async::AI>, and can be used to lock critical sections etc. |
40 | |
106 | |
41 | our ($LOOP, $ASYNC); |
107 | =cut |
|
|
108 | |
|
|
109 | our ($LOOP, $INTERRUPT); |
42 | |
110 | |
43 | sub default() { |
111 | sub default() { |
44 | $LOOP || do { |
112 | $LOOP || do { |
45 | $LOOP = new EV::Loop::Async; |
113 | $LOOP = new EV::Loop::Async; |
46 | # $ASYNC = $LOOP->async; |
114 | $INTERRUPT = $LOOP->interrupt; |
47 | |
115 | |
48 | $LOOP |
116 | $LOOP |
49 | } |
117 | } |
50 | } |
118 | } |
51 | |
119 | |
|
|
120 | =item $EV::Loop::Async::LOOP |
52 | |
121 | |
|
|
122 | The default async loop, available after the first call to |
|
|
123 | C<EV::Loop::Async::default>. |
|
|
124 | |
|
|
125 | =item $EV::Loop::Async::INTERRUPT |
|
|
126 | |
|
|
127 | The default loop's L<Async::Interrupt> object, for easy access. |
|
|
128 | |
|
|
129 | Example: create a section of code where no callback invocations will |
|
|
130 | interrupt: |
|
|
131 | |
|
|
132 | { |
|
|
133 | $EV::Loop::Async::INTERRUPT->scope_block; |
|
|
134 | # no default loop callbacks will be executed here. |
|
|
135 | # the loop will not be locked, however. |
|
|
136 | } |
|
|
137 | |
|
|
138 | Example: embed the default EV::Async::Loop loop into the default L<EV> |
|
|
139 | loop (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 | |
53 | =item $loop = new EV::Loop $flags, [Async-Interrupt-Arguments...] |
146 | =item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...] |
54 | |
147 | |
55 | This constructor: |
148 | This constructor: |
56 | |
149 | |
57 | =over 4 |
150 | =over 4 |
58 | |
151 | |
59 | =item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>). |
152 | =item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>). |
60 | |
153 | |
61 | =item 2. creates a new L<Async::Interrupt> object and attaches itself to it. |
154 | =item 2. creates a new L<Async::Interrupt> object and attaches itself to it. |
62 | |
155 | |
63 | =item 3. locks the loop (see below). |
|
|
64 | |
|
|
65 | =item 4. creates a new background thread. |
156 | =item 3. creates a new background thread. |
66 | |
157 | |
67 | =item 5. runs C<< $loop->run >> in that thread. |
158 | =item 4. runs C<< $loop->run >> in that thread. |
68 | |
159 | |
69 | =back |
160 | =back |
|
|
161 | |
|
|
162 | The resulting loop will be running and unlocked when it is returned. |
|
|
163 | |
|
|
164 | Example: create a new loop, block it's interrupt object and embed |
|
|
165 | it into the foreground L<AnyEvent> event loop. This basically runs the |
|
|
166 | C<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 | ); |
70 | |
182 | |
71 | =cut |
183 | =cut |
72 | |
184 | |
73 | sub new { |
185 | sub new { |
74 | my ($class, $flags, @asy) = @_; |
186 | my ($class, $flags, @asy) = @_; |
75 | |
187 | |
76 | my $self = bless $class->SUPER::new ($flags), $class; |
188 | my $self = bless $class->SUPER::new ($flags), $class; |
77 | my ($c_func, $c_arg) = _c_func $self; |
189 | my ($c_func, $c_arg) = _c_func $self; |
78 | 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]; |
79 | $self->_attach ($asy, $asy->signal_func); |
191 | _attach $self, $asy, $asy->signal_func; |
80 | |
192 | |
81 | $self |
193 | $self |
82 | } |
194 | } |
83 | |
195 | |
84 | =item $loop->nudge |
196 | =item $loop->notify |
85 | |
197 | |
86 | Wake up the asynchronous loop. This is useful after registering a new |
198 | Wake up the asynchronous loop. This is useful after registering a new |
87 | watcher, to ensure that the background event loop integrates the new |
199 | watcher, to ensure that the background event loop integrates the new |
88 | watcher(s) (which only happens when it iterates, which you can force by |
200 | watcher(s) (which only happens when it iterates, which you can force by |
89 | calling this method). |
201 | calling this method). |
90 | |
202 | |
91 | Without calling this method, the event loop I<eventually> takes notice |
203 | Without calling this method, the event loop I<eventually> takes notice |
92 | of new watchers, bit when this happens is not wlel-defined (can be |
204 | of new watchers, bit when this happens is not well-defined (can be |
93 | instantaneous, or take a few hours). |
205 | instantaneous, or take a few hours). |
94 | |
206 | |
95 | No locking is required. |
207 | No locking is required. |
96 | |
208 | |
97 | Example: lock the loop, create a timer, nudge the loop so it takes notice |
209 | Example: lock the loop, create a timer, nudge the loop so it takes notice |
… | |
… | |
101 | my $flag; |
213 | my $flag; |
102 | |
214 | |
103 | { |
215 | { |
104 | $loop->scope_lock; |
216 | $loop->scope_lock; |
105 | $timer = $loop->timer (1, 0, sub { $flag = 1 }); |
217 | $timer = $loop->timer (1, 0, sub { $flag = 1 }); |
106 | $loop->nudge; |
218 | $loop->notify; |
107 | } |
219 | } |
108 | |
220 | |
109 | 1 until $flag; |
221 | 1 until $flag; |
|
|
222 | |
|
|
223 | =item $loop->lock |
|
|
224 | |
|
|
225 | =item $loop->unlock |
|
|
226 | |
|
|
227 | Lock/unlock the loop data structures. Since the event loop runs in |
|
|
228 | a separate thread, you have to lock the loop data structures before |
|
|
229 | accessing them in any way. Since I was lazy, you have to do this manually. |
|
|
230 | |
|
|
231 | You must lock under the same conditions as you would have to lock the |
|
|
232 | underlying C library, e.g. when starting or stopping watchers (but not |
|
|
233 | when creating or destroying them, but note that create and destroy often |
|
|
234 | starts and stops for you, in which case you have to lock). |
|
|
235 | |
|
|
236 | When in doubt, lock. |
|
|
237 | |
|
|
238 | See also the next method, C<< $loop->scope_lock >> for a more failsafe way |
|
|
239 | to lock parts of your code. |
|
|
240 | |
|
|
241 | Note that there must be exactly one call of "unblock" for every previous |
|
|
242 | call to "block" (i.e. calls can nest). |
|
|
243 | |
|
|
244 | =item $loop->scope_lock |
|
|
245 | |
|
|
246 | Calls C<lock> immediately, and C<unlock> automatically whent he current |
|
|
247 | scope is left. |
|
|
248 | |
|
|
249 | =item $loop->set_max_foreground_loops ($max_loops) |
|
|
250 | |
|
|
251 | The background loop will immediately stop polling for new events after it |
|
|
252 | has collected at least one new event, regardless of how long it then takes |
|
|
253 | to actually handle them. |
|
|
254 | |
|
|
255 | When Perl finally handles the events, there could be many more ready |
|
|
256 | file descriptors. To improve latency and performance, you can ask |
|
|
257 | C<EV::Loop::Async> to loop an additional number of times in the foreground |
|
|
258 | after invoking the callbacks, effectively doing the polling in the |
|
|
259 | foreground. |
|
|
260 | |
|
|
261 | The default is C<0>, meaning that no foreground polling will be done. A |
|
|
262 | value of C<1> means that, after handling the pending events, it will call |
|
|
263 | C<< $loop->loop (EV::LOOP_NONBLOCK) >> and handle the resulting events, if |
|
|
264 | any. A value of C<2> means that this will be iterated twice. |
|
|
265 | |
|
|
266 | When a foreground event poll does not yield any new events, then no |
|
|
267 | further iterations will be made, so this is only a I<maximum> value of |
|
|
268 | additional loop runs. |
|
|
269 | |
|
|
270 | Take also note of the standard EV C<set_io_collect_interval> |
|
|
271 | functionality, which can achieve a similar, but different, effect - YMMV. |
|
|
272 | |
|
|
273 | =back |
110 | |
274 | |
111 | =head1 SEE ALSO |
275 | =head1 SEE ALSO |
112 | |
276 | |
113 | L<EV>, L<Async::Interrupt>. |
277 | L<EV>, L<Async::Interrupt>. |
114 | |
278 | |