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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.15 by root, Fri Jul 17 14:59:47 2009 UTC vs.
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC

… …
88I<running> interpreter, there is optional support for signalling a pipe 88I<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
90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> 90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91and C<write> syscall. 91and 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
97package Async::Interrupt; 99package Async::Interrupt;
… …
101BEGIN { 103BEGIN {
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
… …
194This can be used to ensure that async notifications will interrupt event 196This can be used to ensure that async notifications will interrupt event
195frameworks as well. 197frameworks as well.
196 198
197Note that C<Async::Interrupt> will create a suitable signal fd 199Note that C<Async::Interrupt> will create a suitable signal fd
198automatically when your program requests one, so you don't have to specify 200automatically when your program requests one, so you don't have to specify
199this agrument when all you want is an extra file descriptor to watch. 201this argument when all you want is an extra file descriptor to watch.
202
203If you want to share a single event pipe between multiple Async::Interrupt
204objects, you can use the C<Async::Interrupt::EventPipe> class to manage
205those.
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
262This signals the given async object from Perl code. Semi-obviously, this 268This signals the given async object from Perl code. Semi-obviously, this
263will instantly trigger the callback invocation. 269will instantly trigger the callback invocation.
… …
311Note that the only valid oepration on this file descriptor is to wait 317Note that the only valid oepration on this file descriptor is to wait
312until it is readable. The fd might belong currently to a pipe, a tcp 318until it is readable. The fd might belong currently to a pipe, a tcp
313socket, or an eventfd, depending on the platform, and is guaranteed to be 319socket, or an eventfd, depending on the platform, and is guaranteed to be
314C<select>able. 320C<select>able.
315 321
322=item $async->pipe_autodrain ($enable)
323
324Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
325enabled). When automatic draining is enabled, then Async::Interrupt will
326automatically clear the pipe. Otherwise the user is responsible for this
327draining.
328
329This is useful when you want to share one pipe among many Async::Interrupt
330objects.
331
316=item $async->post_fork 332=item $async->post_fork
317 333
318The object will not normally be usable after a fork (as the pipe fd is 334The object will not normally be usable after a fork (as the pipe fd is
319shared between processes). Calling this method after a fork in the child 335shared between processes). Calling this method after a fork in the child
320ensures that the object will work as expected again. It only needs to be 336ensures that the object will work as expected again. It only needs to be
… …
323This only works when the pipe was created by Async::Interrupt. 339This only works when the pipe was created by Async::Interrupt.
324 340
325Async::Interrupt ensures that the reading file descriptor does not change 341Async::Interrupt ensures that the reading file descriptor does not change
326it's value. 342it's value.
327 343
344=back
345
346=head1 THE Async::Interrupt::EventPipe CLASS
347
348Pipes are the predominent utility to make asynchronous signals
349synchronous. However, pipes are hard to come by: they don't exist on the
350broken windows platform, and on GNU/Linux systems, you might want to use
351an C<eventfd> instead.
352
353This class creates selectable event pipes in a portable fashion: on
354windows, it will try to create a tcp socket pair, on GNU/Linux, it will
355try to create an eventfd and everywhere else it will try to use a normal
356pipe.
357
358=over 4
359
360=item $epipe = new Async::Interrupt::EventPipe
361
362This creates and returns an eventpipe object. This object is simply a
363blessed array reference:
364
365=item ($r_fd, $w_fd) = $epipe->filenos
366
367Returns the read-side file descriptor and the write-side file descriptor.
368
369Example: pass an eventpipe object as pipe to the Async::Interrupt
370constructor, 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
378Return only the reading/listening side.
379
380=item $epipe->signal
381
382Write something to the pipe, in a portable fashion.
383
384=item $epipe->drain
385
386Drain (empty) the pipe.
387
388=item $epipe->renew
389
390Recreates the pipe (useful after a fork). The reading side will not change
391it's file descriptor number, but the writing side might.
392
393=back
394
328=cut 395=cut
329 396
3301; 3971;
331
332=back
333 398
334=head1 EXAMPLE 399=head1 EXAMPLE
335 400
336There really should be a complete C/XS example. Bug me about it. Better 401There really should be a complete C/XS example. Bug me about it. Better
337yet, create one. 402yet, create one.

Diff Legend

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