… | |
… | |
88 | I<running> interpreter, there is optional support for signalling a pipe |
88 | I<running> interpreter, there is optional support for signalling a pipe |
89 | - that means you can also wait for the pipe to become readable (e.g. via |
89 | - that means you can also wait for the pipe to become readable (e.g. via |
90 | L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> |
90 | L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> |
91 | and C<write> syscall. |
91 | and C<write> syscall. |
92 | |
92 | |
|
|
93 | =head1 THE Async::Interrupt CLASS |
|
|
94 | |
93 | =over 4 |
95 | =over 4 |
94 | |
96 | |
95 | =cut |
97 | =cut |
96 | |
98 | |
97 | package Async::Interrupt; |
99 | package Async::Interrupt; |
… | |
… | |
101 | BEGIN { |
103 | BEGIN { |
102 | # the next line forces initialisation of internal |
104 | # the next line forces initialisation of internal |
103 | # signal handling # variables |
105 | # signal handling # variables |
104 | $SIG{KILL} = sub { }; |
106 | $SIG{KILL} = sub { }; |
105 | |
107 | |
106 | our $VERSION = '0.501'; |
108 | our $VERSION = '0.6'; |
107 | |
109 | |
108 | require XSLoader; |
110 | require XSLoader; |
109 | XSLoader::load ("Async::Interrupt", $VERSION); |
111 | XSLoader::load ("Async::Interrupt", $VERSION); |
110 | } |
112 | } |
111 | |
113 | |
… | |
… | |
194 | This can be used to ensure that async notifications will interrupt event |
196 | This can be used to ensure that async notifications will interrupt event |
195 | frameworks as well. |
197 | frameworks as well. |
196 | |
198 | |
197 | Note that C<Async::Interrupt> will create a suitable signal fd |
199 | Note that C<Async::Interrupt> will create a suitable signal fd |
198 | automatically when your program requests one, so you don't have to specify |
200 | automatically when your program requests one, so you don't have to specify |
199 | this agrument when all you want is an extra file descriptor to watch. |
201 | this argument when all you want is an extra file descriptor to watch. |
|
|
202 | |
|
|
203 | If you want to share a single event pipe between multiple Async::Interrupt |
|
|
204 | objects, you can use the C<Async::Interrupt::EventPipe> class to manage |
|
|
205 | those. |
200 | |
206 | |
201 | =back |
207 | =back |
202 | |
208 | |
203 | =cut |
209 | =cut |
204 | |
210 | |
… | |
… | |
253 | CODE: |
259 | CODE: |
254 | valuep = (IV *)addr; |
260 | valuep = (IV *)addr; |
255 | |
261 | |
256 | // code in a loop, waiting |
262 | // code in a loop, waiting |
257 | while (!*valuep) |
263 | while (!*valuep) |
258 | ; // do soemthing |
264 | ; // do something |
259 | |
265 | |
260 | =item $async->signal ($value=1) |
266 | =item $async->signal ($value=1) |
261 | |
267 | |
262 | This signals the given async object from Perl code. Semi-obviously, this |
268 | This signals the given async object from Perl code. Semi-obviously, this |
263 | will instantly trigger the callback invocation. |
269 | will instantly trigger the callback invocation. |
… | |
… | |
311 | Note that the only valid oepration on this file descriptor is to wait |
317 | Note that the only valid oepration on this file descriptor is to wait |
312 | until it is readable. The fd might belong currently to a pipe, a tcp |
318 | until it is readable. The fd might belong currently to a pipe, a tcp |
313 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
319 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
314 | C<select>able. |
320 | C<select>able. |
315 | |
321 | |
|
|
322 | =item $async->pipe_autodrain ($enable) |
|
|
323 | |
|
|
324 | Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default: |
|
|
325 | enabled). When automatic draining is enabled, then Async::Interrupt will |
|
|
326 | automatically clear the pipe. Otherwise the user is responsible for this |
|
|
327 | draining. |
|
|
328 | |
|
|
329 | This is useful when you want to share one pipe among many Async::Interrupt |
|
|
330 | objects. |
|
|
331 | |
316 | =item $async->post_fork |
332 | =item $async->post_fork |
317 | |
333 | |
318 | The object will not normally be usable after a fork (as the pipe fd is |
334 | The object will not normally be usable after a fork (as the pipe fd is |
319 | shared between processes). Calling this method after a fork in the child |
335 | shared between processes). Calling this method after a fork in the child |
320 | ensures that the object will work as expected again. It only needs to be |
336 | ensures that the object will work as expected again. It only needs to be |
… | |
… | |
323 | This only works when the pipe was created by Async::Interrupt. |
339 | This only works when the pipe was created by Async::Interrupt. |
324 | |
340 | |
325 | Async::Interrupt ensures that the reading file descriptor does not change |
341 | Async::Interrupt ensures that the reading file descriptor does not change |
326 | it's value. |
342 | it's value. |
327 | |
343 | |
|
|
344 | =back |
|
|
345 | |
|
|
346 | =head1 THE Async::Interrupt::EventPipe CLASS |
|
|
347 | |
|
|
348 | Pipes are the predominent utility to make asynchronous signals |
|
|
349 | synchronous. However, pipes are hard to come by: they don't exist on the |
|
|
350 | broken windows platform, and on GNU/Linux systems, you might want to use |
|
|
351 | an C<eventfd> instead. |
|
|
352 | |
|
|
353 | This class creates selectable event pipes in a portable fashion: on |
|
|
354 | windows, it will try to create a tcp socket pair, on GNU/Linux, it will |
|
|
355 | try to create an eventfd and everywhere else it will try to use a normal |
|
|
356 | pipe. |
|
|
357 | |
|
|
358 | =over 4 |
|
|
359 | |
|
|
360 | =item $epipe = new Async::Interrupt::EventPipe |
|
|
361 | |
|
|
362 | This creates and returns an eventpipe object. This object is simply a |
|
|
363 | blessed array reference: |
|
|
364 | |
|
|
365 | =item ($r_fd, $w_fd) = $epipe->filenos |
|
|
366 | |
|
|
367 | Returns the read-side file descriptor and the write-side file descriptor. |
|
|
368 | |
|
|
369 | Example: pass an eventpipe object as pipe to the Async::Interrupt |
|
|
370 | constructor, and create an AnyEvent watcher for the read side. |
|
|
371 | |
|
|
372 | my $epipe = new Async::Interrupt::EventPipe; |
|
|
373 | my $asy = new Async::Interrupt pipe => [$epipe->filenos]; |
|
|
374 | my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { }); |
|
|
375 | |
|
|
376 | =item $r_fd = $epipe->fileno |
|
|
377 | |
|
|
378 | Return only the reading/listening side. |
|
|
379 | |
|
|
380 | =item $epipe->signal |
|
|
381 | |
|
|
382 | Write something to the pipe, in a portable fashion. |
|
|
383 | |
|
|
384 | =item $epipe->drain |
|
|
385 | |
|
|
386 | Drain (empty) the pipe. |
|
|
387 | |
|
|
388 | =item $epipe->renew |
|
|
389 | |
|
|
390 | Recreates the pipe (useful after a fork). The reading side will not change |
|
|
391 | it's file descriptor number, but the writing side might. |
|
|
392 | |
|
|
393 | =back |
|
|
394 | |
328 | =cut |
395 | =cut |
329 | |
396 | |
330 | 1; |
397 | 1; |
331 | |
|
|
332 | =back |
|
|
333 | |
398 | |
334 | =head1 EXAMPLE |
399 | =head1 EXAMPLE |
335 | |
400 | |
336 | There really should be a complete C/XS example. Bug me about it. Better |
401 | There really should be a complete C/XS example. Bug me about it. Better |
337 | yet, create one. |
402 | yet, create one. |