Async-Interrupt/Interrupt.pm

=head1 NAME

Async::Interrupt - allow C/XS libraries to interrupt perl asynchronously

=head1 SYNOPSIS

 use Async::Interrupt;

=head1 DESCRIPTION

This module implements a single feature only of interest to advanced perl
modules, namely asynchronous interruptions (think "UNIX signals", which
are very similar).

Sometimes, modules wish to run code asynchronously (in another thread,
or from a signal handler), and then signal the perl interpreter on
certain events. One common way is to write some data to a pipe and use an
event handling toolkit to watch for I/O events. Another way is to send
a signal. Those methods are slow, and in the case of a pipe, also not
asynchronous - it won't interrupt a running perl interpreter.

This module implements asynchronous notifications that enable you to
signal running perl code from another thread, asynchronously, and
sometimes even without using a single syscall.

=head2 USAGE SCENARIOS

=over 4

=item Race-free signal handling

There seems to be no way to do race-free signal handling in perl: to
catch a signal, you have to execute Perl code, and between entering the
interpreter C<select> function (or other blocking functions) and executing
the select syscall is a small but relevant timespan during which signals
will be queued, but perl signal handlers will not be executed and the
blocking syscall will not be interrupted.

You can use this module to bind a signal to a callback while at the same
time activating an event pipe that you can C<select> on, fixing the race
completely.

This can be used to implement the signal hadling in event loops,
e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.

=item Background threads want speedy reporting

Assume you want very exact timing, and you can spare an extra cpu core
for that. Then you can run an extra thread that signals your perl
interpreter. This means you can get a very exact timing source while your
perl code is number crunching, without even using a syscall to communicate
between your threads.

For example the deliantra game server uses a variant of this technique
to interrupt background processes regularly to send map updates to game
clients.

L<IO::AIO> and L<BDB> could also use this to speed up result reporting.

=item Speedy event loop invocation

One could use this module e.g. in L<Coro> to interrupt a running coro-thread
and cause it to enter the event loop.

Or one could bind to C<SIGIO> and tell some important sockets to send this
signal, causing the event loop to be entered to reduce network latency.

=back

=head2 HOW TO USE

You can use this module by creating an C<Async::Interrupt> object for each
such event source. This object stores a perl and/or a C-level callback
that is invoked when the C<Async::Interrupt> object gets signalled. It is
executed at the next time the perl interpreter is running (i.e. it will
interrupt a computation, but not an XS function or a syscall).

You can signal the C<Async::Interrupt> object either by calling it's C<<
->signal >> method, or, more commonly, by calling a C function. There is
also the built-in (POSIX) signal source.

The C<< ->signal_func >> returns the address of the C function that is to
be called (plus an argument to be used during the call). The signalling
function also takes an integer argument in the range SIG_ATOMIC_MIN to
SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).

Since this kind of interruption is fast, but can only interrupt a
I<running> interpreter, there is optional support for signalling a pipe
- that means you can also wait for the pipe to become readable (e.g. via
L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
and C<write> syscall.

=head1 THE Async::Interrupt CLASS

=over 4

=cut

package Async::Interrupt;

use common::sense;

BEGIN {
   # the next line forces initialisation of internal
   # signal handling # variables
   $SIG{KILL} = sub { };

   our $VERSION = '0.6';

   require XSLoader;
   XSLoader::load ("Async::Interrupt", $VERSION);
}

our $DIED = sub { warn "$@" };

=item $async = new Async::Interrupt key => value...

Creates a new Async::Interrupt object. You may only use async
notifications on this object while it exists, so you need to keep a
reference to it at all times while it is used.

Optional constructor arguments include (normally you would specify at
least one of C<cb> or C<c_cb>).

=over 4

=item cb => $coderef->($value)

Registers a perl callback to be invoked whenever the async interrupt is
signalled.

Note that, since this callback can be invoked at basically any time, it
must not modify any well-known global variables such as C<$/> without
restoring them again before returning.

The exceptions are C<$!> and C<$@>, which are saved and restored by
Async::Interrupt.

If the callback should throw an exception, then it will be caught,
and C<$Async::Interrupt::DIED> will be called with C<$@> containing
the exception.  The default will simply C<warn> about the message and
continue.

=item c_cb => [$c_func, $c_arg]

Registers a C callback the be invoked whenever the async interrupt is
signalled.

The C callback must have the following prototype:

   void c_func (pTHX_ void *c_arg, int value);

Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
C<$value> is the C<value> passed to some earlier call to either C<$signal>
or the C<signal_func> function.

Note that, because the callback can be invoked at almost any time, you
have to be careful at saving and restoring global variables that Perl
might use (the exception is C<errno>, which is saved and restored by
Async::Interrupt). The callback itself runs as part of the perl context,
so you can call any perl functions and modify any perl data structures (in
which case the requirements set out for C<cb> apply as well).

=item var => $scalar_ref

When specified, then the given argument must be a reference to a
scalar. The scalar will be set to C<0> intiially. Signalling the interrupt
object will set it to the passed value, handling the interrupt will reset
it to C<0> again.

Note that the only thing you are legally allowed to do is to is to check
the variable in a boolean or integer context (e.g. comparing it with a
string, or printing it, will I<destroy> it and might cause your program to
crash or worse).

=item signal => $signame_or_value

When this parameter is specified, then the Async::Interrupt will hook the
given signal, that is, it will effectively call C<< ->signal (0) >> each time
the given signal is caught by the process.

Only one async can hook a given signal, and the signal will be restored to
defaults when the Async::Interrupt object gets destroyed.

=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]

Specifies two file descriptors (or file handles) that should be signalled
whenever the async interrupt is signalled. This means a single octet will
be written to it, and before the callback is being invoked, it will be
read again. Due to races, it is unlikely but possible that multiple octets
are written. It is required that the file handles are both in nonblocking
mode.

The object will keep a reference to the file handles.

This can be used to ensure that async notifications will interrupt event
frameworks as well.

Note that C<Async::Interrupt> will create a suitable signal fd
automatically when your program requests one, so you don't have to specify
this argument when all you want is an extra file descriptor to watch.

If you want to share a single event pipe between multiple Async::Interrupt
objects, you can use the C<Async::Interrupt::EventPipe> class to manage
those.

=back

=cut

sub new {
   my ($class, %arg) = @_;

   bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
}

=item ($signal_func, $signal_arg) = $async->signal_func

Returns the address of a function to call asynchronously. The function has
the following prototype and needs to be passed the specified C<$c_arg>,
which is a C<void *> cast to C<IV>:

   void (*signal_func) (void *signal_arg, int value)

An example call would look like:

   signal_func (signal_arg, 0);

The function is safe to call from within signal and thread contexts, at
any time. The specified C<value> is passed to both C and Perl callback.

C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
(1..127 is portable).

If the function is called while the Async::Interrupt object is already
signaled but before the callbacks are being executed, then the stored
C<value> is either the old or the new one. Due to the asynchronous
nature of the code, the C<value> can even be passed to two consecutive
invocations of the callback.

=item $address = $async->c_var

Returns the address (cast to IV) of an C<IV> variable. The variable is set
to C<0> initially and gets set to the passed value whenever the object
gets signalled, and reset to C<0> once the interrupt has been handled.

Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
handle any interrupts.

Example: call some XS function to store the address, then show C code
waiting for it.

   my_xs_func $async->c_var;

   static IV *valuep;

   void
   my_xs_func (void *addr)
           CODE:
           valuep = (IV *)addr;

   // code in a loop, waiting
   while (!*valuep)
     ; // do something

=item $async->signal ($value=1)

This signals the given async object from Perl code. Semi-obviously, this
will instantly trigger the callback invocation.

C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
(1..127 is portable).

=item $async->block

=item $async->unblock

Sometimes you need a "critical section" of code that will not be
interrupted by an Async::Interrupt. This can be implemented by calling C<<
$async->block >> before the critical section, and C<< $async->unblock >>
afterwards.

Note that there must be exactly one call of C<unblock> for every previous
call to C<block> (i.e. calls can nest).

Since ensuring this in the presence of exceptions and threads is
usually more difficult than you imagine, I recommend using C<<
$async->scoped_block >> instead.

=item $async->scope_block

This call C<< $async->block >> and installs a handler that is called when
the current scope is exited (via an exception, by canceling the Coro
thread, by calling last/goto etc.).

This is the recommended (and fastest) way to implement critical sections.

=item $async->pipe_enable

=item $async->pipe_disable

Enable/disable signalling the pipe when the interrupt occurs (default is
enabled). Writing to a pipe is relatively expensive, so it can be disabled
when you know you are not waiting for it (for example, with L<EV> you
could disable the pipe in a check watcher, and enable it in a prepare
watcher).

Note that currently, while C<pipe_disable> is in effect, no attempt to
read from the pipe will be done when handling events. This might change as
soon as I realize why this is a mistake.

=item $fileno = $async->pipe_fileno

Returns the reading side of the signalling pipe. If no signalling pipe is
currently attached to the object, it will dynamically create one.

Note that the only valid oepration on this file descriptor is to wait
until it is readable. The fd might belong currently to a pipe, a tcp
socket, or an eventfd, depending on the platform, and is guaranteed to be
C<select>able.

=item $async->pipe_autodrain ($enable)

Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
enabled). When automatic draining is enabled, then Async::Interrupt will
automatically clear the pipe. Otherwise the user is responsible for this
draining.

This is useful when you want to share one pipe among many Async::Interrupt
objects.

=item $async->post_fork

The object will not normally be usable after a fork (as the pipe fd is
shared between processes). Calling this method after a fork in the child
ensures that the object will work as expected again. It only needs to be
called when the async object is used in the child.

This only works when the pipe was created by Async::Interrupt.

Async::Interrupt ensures that the reading file descriptor does not change
it's value.

=back

=head1 THE Async::Interrupt::EventPipe CLASS

Pipes are the predominent utility to make asynchronous signals
synchronous. However, pipes are hard to come by: they don't exist on the
broken windows platform, and on GNU/Linux systems, you might want to use
an C<eventfd> instead.

This class creates selectable event pipes in a portable fashion: on
windows, it will try to create a tcp socket pair, on GNU/Linux, it will
try to create an eventfd and everywhere else it will try to use a normal
pipe.

=over 4

=item $epipe = new Async::Interrupt::EventPipe

This creates and returns an eventpipe object. This object is simply a
blessed array reference:

=item ($r_fd, $w_fd) = $epipe->filenos

Returns the read-side file descriptor and the write-side file descriptor.

Example: pass an eventpipe object as pipe to the Async::Interrupt
constructor, and create an AnyEvent watcher for the read side.

   my $epipe = new Async::Interrupt::EventPipe;
   my $asy = new Async::Interrupt pipe => [$epipe->filenos];
   my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });

=item $r_fd = $epipe->fileno

Return only the reading/listening side.

=item $epipe->signal

Write something to the pipe, in a portable fashion.

=item $epipe->drain

Drain (empty) the pipe.

=item $epipe->renew

Recreates the pipe (useful after a fork). The reading side will not change
it's file descriptor number, but the writing side might.

=back

=cut

1;

=head1 EXAMPLE

There really should be a complete C/XS example. Bug me about it. Better
yet, create one.

=head1 IMPLEMENTATION DETAILS AND LIMITATIONS

This module works by "hijacking" SIGKILL, which is guaranteed to always
exist, but also cannot be caught, so is always available.

Basically, this module fakes the occurance of a SIGKILL signal and
then intercepts the interpreter handling it. This makes normal signal
handling slower (probably unmeasurably, though), but has the advantage
of not requiring a special runops function, nor slowing down normal perl
execution a bit.

It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
modify.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.16
Committed:	Fri Jul 17 21:02:18 2009 UTC (14 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_06
Changes since 1.15:	+70 -5 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Async::Interrupt - allow C/XS libraries to interrupt perl asynchronously
4
5			=head1 SYNOPSIS
6
7			use Async::Interrupt;
8
9			=head1 DESCRIPTION
10
11			This module implements a single feature only of interest to advanced perl
12	root	1.4	modules, namely asynchronous interruptions (think "UNIX signals", which
13	root	1.1	are very similar).
14
15	root	1.8	Sometimes, modules wish to run code asynchronously (in another thread,
16			or from a signal handler), and then signal the perl interpreter on
17			certain events. One common way is to write some data to a pipe and use an
18			event handling toolkit to watch for I/O events. Another way is to send
19			a signal. Those methods are slow, and in the case of a pipe, also not
20			asynchronous - it won't interrupt a running perl interpreter.
21	root	1.1
22			This module implements asynchronous notifications that enable you to
23	root	1.8	signal running perl code from another thread, asynchronously, and
24			sometimes even without using a single syscall.
25	root	1.1
26	root	1.8	=head2 USAGE SCENARIOS
27
28			=over 4
29
30			=item Race-free signal handling
31
32			There seems to be no way to do race-free signal handling in perl: to
33			catch a signal, you have to execute Perl code, and between entering the
34			interpreter C<select> function (or other blocking functions) and executing
35			the select syscall is a small but relevant timespan during which signals
36			will be queued, but perl signal handlers will not be executed and the
37			blocking syscall will not be interrupted.
38
39			You can use this module to bind a signal to a callback while at the same
40			time activating an event pipe that you can C<select> on, fixing the race
41			completely.
42
43			This can be used to implement the signal hadling in event loops,
44			e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
45
46			=item Background threads want speedy reporting
47
48			Assume you want very exact timing, and you can spare an extra cpu core
49			for that. Then you can run an extra thread that signals your perl
50			interpreter. This means you can get a very exact timing source while your
51			perl code is number crunching, without even using a syscall to communicate
52			between your threads.
53
54			For example the deliantra game server uses a variant of this technique
55			to interrupt background processes regularly to send map updates to game
56			clients.
57
58			L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
59
60			=item Speedy event loop invocation
61
62			One could use this module e.g. in L<Coro> to interrupt a running coro-thread
63			and cause it to enter the event loop.
64
65			Or one could bind to C<SIGIO> and tell some important sockets to send this
66			signal, causing the event loop to be entered to reduce network latency.
67
68			=back
69
70			=head2 HOW TO USE
71
72			You can use this module by creating an C<Async::Interrupt> object for each
73			such event source. This object stores a perl and/or a C-level callback
74			that is invoked when the C<Async::Interrupt> object gets signalled. It is
75			executed at the next time the perl interpreter is running (i.e. it will
76			interrupt a computation, but not an XS function or a syscall).
77	root	1.2
78			You can signal the C<Async::Interrupt> object either by calling it's C<<
79	root	1.8	->signal >> method, or, more commonly, by calling a C function. There is
80			also the built-in (POSIX) signal source.
81	root	1.2
82			The C<< ->signal_func >> returns the address of the C function that is to
83			be called (plus an argument to be used during the call). The signalling
84			function also takes an integer argument in the range SIG_ATOMIC_MIN to
85			SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
86
87			Since this kind of interruption is fast, but can only interrupt a
88	root	1.8	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
90			L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91			and C<write> syscall.
92	root	1.2
93	root	1.16	=head1 THE Async::Interrupt CLASS
94
95	root	1.1	=over 4
96
97			=cut
98
99			package Async::Interrupt;
100
101	root	1.10	use common::sense;
102	root	1.2
103	root	1.1	BEGIN {
104	root	1.11	# the next line forces initialisation of internal
105			# signal handling # variables
106			$SIG{KILL} = sub { };
107
108	root	1.16	our $VERSION = '0.6';
109	root	1.1
110			require XSLoader;
111	root	1.11	XSLoader::load ("Async::Interrupt", $VERSION);
112	root	1.1	}
113
114	root	1.2	our $DIED = sub { warn "$@" };
115
116	root	1.1	=item $async = new Async::Interrupt key => value...
117
118			Creates a new Async::Interrupt object. You may only use async
119			notifications on this object while it exists, so you need to keep a
120			reference to it at all times while it is used.
121
122			Optional constructor arguments include (normally you would specify at
123			least one of C<cb> or C<c_cb>).
124
125			=over 4
126
127			=item cb => $coderef->($value)
128
129			Registers a perl callback to be invoked whenever the async interrupt is
130			signalled.
131
132			Note that, since this callback can be invoked at basically any time, it
133	root	1.2	must not modify any well-known global variables such as C<$/> without
134			restoring them again before returning.
135
136			The exceptions are C<$!> and C<$@>, which are saved and restored by
137			Async::Interrupt.
138	root	1.1
139	root	1.2	If the callback should throw an exception, then it will be caught,
140			and C<$Async::Interrupt::DIED> will be called with C<$@> containing
141			the exception. The default will simply C<warn> about the message and
142			continue.
143
144			=item c_cb => [$c_func, $c_arg]
145	root	1.1
146			Registers a C callback the be invoked whenever the async interrupt is
147			signalled.
148
149			The C callback must have the following prototype:
150
151	root	1.2	void c_func (pTHX_ void *c_arg, int value);
152	root	1.1
153	root	1.2	Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
154			C<$value> is the C<value> passed to some earlier call to either C<$signal>
155			or the C<signal_func> function.
156	root	1.1
157			Note that, because the callback can be invoked at almost any time, you
158			have to be careful at saving and restoring global variables that Perl
159	root	1.4	might use (the exception is C<errno>, which is saved and restored by
160	root	1.2	Async::Interrupt). The callback itself runs as part of the perl context,
161			so you can call any perl functions and modify any perl data structures (in
162	root	1.4	which case the requirements set out for C<cb> apply as well).
163	root	1.1
164	root	1.13	=item var => $scalar_ref
165
166			When specified, then the given argument must be a reference to a
167			scalar. The scalar will be set to C<0> intiially. Signalling the interrupt
168			object will set it to the passed value, handling the interrupt will reset
169			it to C<0> again.
170
171			Note that the only thing you are legally allowed to do is to is to check
172			the variable in a boolean or integer context (e.g. comparing it with a
173			string, or printing it, will I<destroy> it and might cause your program to
174			crash or worse).
175
176	root	1.6	=item signal => $signame_or_value
177
178			When this parameter is specified, then the Async::Interrupt will hook the
179			given signal, that is, it will effectively call C<< ->signal (0) >> each time
180			the given signal is caught by the process.
181
182			Only one async can hook a given signal, and the signal will be restored to
183			defaults when the Async::Interrupt object gets destroyed.
184
185	root	1.2	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
186	root	1.1
187	root	1.2	Specifies two file descriptors (or file handles) that should be signalled
188	root	1.1	whenever the async interrupt is signalled. This means a single octet will
189			be written to it, and before the callback is being invoked, it will be
190			read again. Due to races, it is unlikely but possible that multiple octets
191	root	1.2	are written. It is required that the file handles are both in nonblocking
192			mode.
193	root	1.1
194	root	1.2	The object will keep a reference to the file handles.
195	root	1.1
196			This can be used to ensure that async notifications will interrupt event
197			frameworks as well.
198
199	root	1.13	Note that C<Async::Interrupt> will create a suitable signal fd
200			automatically when your program requests one, so you don't have to specify
201	root	1.16	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.
206	root	1.13
207	root	1.1	=back
208
209			=cut
210
211			sub new {
212			my ($class, %arg) = @_;
213
214	root	1.13	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
215	root	1.1	}
216
217	root	1.2	=item ($signal_func, $signal_arg) = $async->signal_func
218	root	1.1
219			Returns the address of a function to call asynchronously. The function has
220			the following prototype and needs to be passed the specified C<$c_arg>,
221			which is a C<void *> cast to C<IV>:
222
223			void (signal_func) (void signal_arg, int value)
224
225			An example call would look like:
226
227			signal_func (signal_arg, 0);
228
229	root	1.2	The function is safe to call from within signal and thread contexts, at
230	root	1.1	any time. The specified C<value> is passed to both C and Perl callback.
231
232	root	1.13	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
233			(1..127 is portable).
234	root	1.2
235	root	1.1	If the function is called while the Async::Interrupt object is already
236			signaled but before the callbacks are being executed, then the stored
237	root	1.2	C<value> is either the old or the new one. Due to the asynchronous
238			nature of the code, the C<value> can even be passed to two consecutive
239			invocations of the callback.
240	root	1.1
241	root	1.13	=item $address = $async->c_var
242
243			Returns the address (cast to IV) of an C<IV> variable. The variable is set
244			to C<0> initially and gets set to the passed value whenever the object
245			gets signalled, and reset to C<0> once the interrupt has been handled.
246
247			Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
248			handle any interrupts.
249
250			Example: call some XS function to store the address, then show C code
251			waiting for it.
252
253			my_xs_func $async->c_var;
254
255			static IV *valuep;
256
257			void
258			my_xs_func (void *addr)
259			CODE:
260			valuep = (IV *)addr;
261
262			// code in a loop, waiting
263			while (!*valuep)
264	root	1.16	; // do something
265	root	1.13
266			=item $async->signal ($value=1)
267	root	1.1
268			This signals the given async object from Perl code. Semi-obviously, this
269			will instantly trigger the callback invocation.
270
271	root	1.13	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
272			(1..127 is portable).
273	root	1.2
274			=item $async->block
275
276	root	1.3	=item $async->unblock
277
278			Sometimes you need a "critical section" of code that will not be
279			interrupted by an Async::Interrupt. This can be implemented by calling C<<
280			$async->block >> before the critical section, and C<< $async->unblock >>
281			afterwards.
282
283	root	1.4	Note that there must be exactly one call of C<unblock> for every previous
284	root	1.3	call to C<block> (i.e. calls can nest).
285
286	root	1.4	Since ensuring this in the presence of exceptions and threads is
287	root	1.3	usually more difficult than you imagine, I recommend using C<<
288			$async->scoped_block >> instead.
289	root	1.2
290	root	1.3	=item $async->scope_block
291
292			This call C<< $async->block >> and installs a handler that is called when
293			the current scope is exited (via an exception, by canceling the Coro
294			thread, by calling last/goto etc.).
295
296			This is the recommended (and fastest) way to implement critical sections.
297	root	1.2
298	root	1.6	=item $async->pipe_enable
299
300			=item $async->pipe_disable
301
302			Enable/disable signalling the pipe when the interrupt occurs (default is
303			enabled). Writing to a pipe is relatively expensive, so it can be disabled
304			when you know you are not waiting for it (for example, with L<EV> you
305			could disable the pipe in a check watcher, and enable it in a prepare
306			watcher).
307
308	root	1.13	Note that currently, while C<pipe_disable> is in effect, no attempt to
309			read from the pipe will be done when handling events. This might change as
310			soon as I realize why this is a mistake.
311
312			=item $fileno = $async->pipe_fileno
313
314			Returns the reading side of the signalling pipe. If no signalling pipe is
315			currently attached to the object, it will dynamically create one.
316
317			Note that the only valid oepration on this file descriptor is to wait
318			until it is readable. The fd might belong currently to a pipe, a tcp
319			socket, or an eventfd, depending on the platform, and is guaranteed to be
320			C<select>able.
321
322	root	1.16	=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
332	root	1.13	=item $async->post_fork
333
334			The object will not normally be usable after a fork (as the pipe fd is
335			shared between processes). Calling this method after a fork in the child
336			ensures that the object will work as expected again. It only needs to be
337			called when the async object is used in the child.
338
339			This only works when the pipe was created by Async::Interrupt.
340
341			Async::Interrupt ensures that the reading file descriptor does not change
342			it's value.
343	root	1.6
344	root	1.16	=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
395	root	1.1	=cut
396
397			1;
398
399	root	1.2	=head1 EXAMPLE
400
401	root	1.8	There really should be a complete C/XS example. Bug me about it. Better
402			yet, create one.
403	root	1.2
404			=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
405
406	root	1.8	This module works by "hijacking" SIGKILL, which is guaranteed to always
407			exist, but also cannot be caught, so is always available.
408	root	1.2
409	root	1.8	Basically, this module fakes the occurance of a SIGKILL signal and
410			then intercepts the interpreter handling it. This makes normal signal
411			handling slower (probably unmeasurably, though), but has the advantage
412			of not requiring a special runops function, nor slowing down normal perl
413			execution a bit.
414
415	root	1.13	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
416			modify.
417	root	1.2
418	root	1.1	=head1 AUTHOR
419
420			Marc Lehmann <schmorp@schmorp.de>
421			http://home.schmorp.de/
422
423			=cut
424