cvsroot/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.

Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
events have arrived.

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> initially. 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<$signal_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 (it does not, as the name
might imply, do anything with POSIX signals).

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

=item $async->signal_hysteresis ($enable)

Enables or disables signal hysteresis (default: disabled). If a POSIX
signal is used as a signal source for the interrupt object, then enabling
signal hysteresis causes Async::Interrupt to reset the signal action to
C<SIG_IGN> in the signal handler and restore it just before handling the
interruption.

When you expect a lot of signals (e.g. when using SIGIO), then enabling
signal hysteresis can reduce the number of handler invocations
considerably, at the cost of two extra syscalls.

Note that setting the signal to C<SIG_IGN> can have unintended side
effects when you fork and exec other programs, as often they do nto expect
signals to be ignored by default.

=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 ($block_func, $block_arg) = $async->scope_block_func

Returns the address of a function that implements the C<scope_block>
functionality.

It has the following prototype and needs to be passed the specified
C<$block_arg>, which is a C<void *> cast to C<IV>:

   void (*block_func) (void *block_arg)

An example call would look like:

   block_func (block_arg);

The function is safe to call only from within the toplevel of a perl XS
function and will call C<LEAVE> and C<ENTER> (in this order!).

=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.17
Committed:	Tue Jul 28 01:19:44 2009 UTC (14 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.16:	+42 -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	root	1.17	Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
59			events have arrived.
60
61	root	1.8	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
62
63			=item Speedy event loop invocation
64
65			One could use this module e.g. in L<Coro> to interrupt a running coro-thread
66			and cause it to enter the event loop.
67
68			Or one could bind to C<SIGIO> and tell some important sockets to send this
69			signal, causing the event loop to be entered to reduce network latency.
70
71			=back
72
73			=head2 HOW TO USE
74
75			You can use this module by creating an C<Async::Interrupt> object for each
76			such event source. This object stores a perl and/or a C-level callback
77			that is invoked when the C<Async::Interrupt> object gets signalled. It is
78			executed at the next time the perl interpreter is running (i.e. it will
79			interrupt a computation, but not an XS function or a syscall).
80	root	1.2
81			You can signal the C<Async::Interrupt> object either by calling it's C<<
82	root	1.8	->signal >> method, or, more commonly, by calling a C function. There is
83			also the built-in (POSIX) signal source.
84	root	1.2
85			The C<< ->signal_func >> returns the address of the C function that is to
86			be called (plus an argument to be used during the call). The signalling
87			function also takes an integer argument in the range SIG_ATOMIC_MIN to
88			SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
89
90			Since this kind of interruption is fast, but can only interrupt a
91	root	1.8	I<running> interpreter, there is optional support for signalling a pipe
92			- that means you can also wait for the pipe to become readable (e.g. via
93			L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
94			and C<write> syscall.
95	root	1.2
96	root	1.16	=head1 THE Async::Interrupt CLASS
97
98	root	1.1	=over 4
99
100			=cut
101
102			package Async::Interrupt;
103
104	root	1.10	use common::sense;
105	root	1.2
106	root	1.1	BEGIN {
107	root	1.11	# the next line forces initialisation of internal
108			# signal handling # variables
109			$SIG{KILL} = sub { };
110
111	root	1.16	our $VERSION = '0.6';
112	root	1.1
113			require XSLoader;
114	root	1.11	XSLoader::load ("Async::Interrupt", $VERSION);
115	root	1.1	}
116
117	root	1.2	our $DIED = sub { warn "$@" };
118
119	root	1.1	=item $async = new Async::Interrupt key => value...
120
121			Creates a new Async::Interrupt object. You may only use async
122			notifications on this object while it exists, so you need to keep a
123			reference to it at all times while it is used.
124
125			Optional constructor arguments include (normally you would specify at
126			least one of C<cb> or C<c_cb>).
127
128			=over 4
129
130			=item cb => $coderef->($value)
131
132			Registers a perl callback to be invoked whenever the async interrupt is
133			signalled.
134
135			Note that, since this callback can be invoked at basically any time, it
136	root	1.2	must not modify any well-known global variables such as C<$/> without
137			restoring them again before returning.
138
139			The exceptions are C<$!> and C<$@>, which are saved and restored by
140			Async::Interrupt.
141	root	1.1
142	root	1.2	If the callback should throw an exception, then it will be caught,
143			and C<$Async::Interrupt::DIED> will be called with C<$@> containing
144			the exception. The default will simply C<warn> about the message and
145			continue.
146
147			=item c_cb => [$c_func, $c_arg]
148	root	1.1
149			Registers a C callback the be invoked whenever the async interrupt is
150			signalled.
151
152			The C callback must have the following prototype:
153
154	root	1.2	void c_func (pTHX_ void *c_arg, int value);
155	root	1.1
156	root	1.2	Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
157			C<$value> is the C<value> passed to some earlier call to either C<$signal>
158			or the C<signal_func> function.
159	root	1.1
160			Note that, because the callback can be invoked at almost any time, you
161			have to be careful at saving and restoring global variables that Perl
162	root	1.4	might use (the exception is C<errno>, which is saved and restored by
163	root	1.2	Async::Interrupt). The callback itself runs as part of the perl context,
164			so you can call any perl functions and modify any perl data structures (in
165	root	1.4	which case the requirements set out for C<cb> apply as well).
166	root	1.1
167	root	1.13	=item var => $scalar_ref
168
169			When specified, then the given argument must be a reference to a
170	root	1.17	scalar. The scalar will be set to C<0> initially. Signalling the interrupt
171	root	1.13	object will set it to the passed value, handling the interrupt will reset
172			it to C<0> again.
173
174			Note that the only thing you are legally allowed to do is to is to check
175			the variable in a boolean or integer context (e.g. comparing it with a
176			string, or printing it, will I<destroy> it and might cause your program to
177			crash or worse).
178
179	root	1.6	=item signal => $signame_or_value
180
181			When this parameter is specified, then the Async::Interrupt will hook the
182			given signal, that is, it will effectively call C<< ->signal (0) >> each time
183			the given signal is caught by the process.
184
185			Only one async can hook a given signal, and the signal will be restored to
186			defaults when the Async::Interrupt object gets destroyed.
187
188	root	1.2	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
189	root	1.1
190	root	1.2	Specifies two file descriptors (or file handles) that should be signalled
191	root	1.1	whenever the async interrupt is signalled. This means a single octet will
192			be written to it, and before the callback is being invoked, it will be
193			read again. Due to races, it is unlikely but possible that multiple octets
194	root	1.2	are written. It is required that the file handles are both in nonblocking
195			mode.
196	root	1.1
197	root	1.2	The object will keep a reference to the file handles.
198	root	1.1
199			This can be used to ensure that async notifications will interrupt event
200			frameworks as well.
201
202	root	1.13	Note that C<Async::Interrupt> will create a suitable signal fd
203			automatically when your program requests one, so you don't have to specify
204	root	1.16	this argument when all you want is an extra file descriptor to watch.
205
206			If you want to share a single event pipe between multiple Async::Interrupt
207			objects, you can use the C<Async::Interrupt::EventPipe> class to manage
208			those.
209	root	1.13
210	root	1.1	=back
211
212			=cut
213
214			sub new {
215			my ($class, %arg) = @_;
216
217	root	1.13	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
218	root	1.1	}
219
220	root	1.2	=item ($signal_func, $signal_arg) = $async->signal_func
221	root	1.1
222	root	1.17	Returns the address of a function to call asynchronously. The function
223			has the following prototype and needs to be passed the specified
224			C<$signal_arg>, which is a C<void *> cast to C<IV>:
225	root	1.1
226			void (signal_func) (void signal_arg, int value)
227
228			An example call would look like:
229
230			signal_func (signal_arg, 0);
231
232	root	1.2	The function is safe to call from within signal and thread contexts, at
233	root	1.1	any time. The specified C<value> is passed to both C and Perl callback.
234
235	root	1.13	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
236			(1..127 is portable).
237	root	1.2
238	root	1.1	If the function is called while the Async::Interrupt object is already
239			signaled but before the callbacks are being executed, then the stored
240	root	1.2	C<value> is either the old or the new one. Due to the asynchronous
241			nature of the code, the C<value> can even be passed to two consecutive
242			invocations of the callback.
243	root	1.1
244	root	1.13	=item $address = $async->c_var
245
246			Returns the address (cast to IV) of an C<IV> variable. The variable is set
247			to C<0> initially and gets set to the passed value whenever the object
248			gets signalled, and reset to C<0> once the interrupt has been handled.
249
250			Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
251			handle any interrupts.
252
253			Example: call some XS function to store the address, then show C code
254			waiting for it.
255
256			my_xs_func $async->c_var;
257
258			static IV *valuep;
259
260			void
261			my_xs_func (void *addr)
262			CODE:
263			valuep = (IV *)addr;
264
265			// code in a loop, waiting
266			while (!*valuep)
267	root	1.16	; // do something
268	root	1.13
269			=item $async->signal ($value=1)
270	root	1.1
271			This signals the given async object from Perl code. Semi-obviously, this
272	root	1.17	will instantly trigger the callback invocation (it does not, as the name
273			might imply, do anything with POSIX signals).
274	root	1.1
275	root	1.13	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
276			(1..127 is portable).
277	root	1.2
278	root	1.17	=item $async->signal_hysteresis ($enable)
279
280			Enables or disables signal hysteresis (default: disabled). If a POSIX
281			signal is used as a signal source for the interrupt object, then enabling
282			signal hysteresis causes Async::Interrupt to reset the signal action to
283			C<SIG_IGN> in the signal handler and restore it just before handling the
284			interruption.
285
286			When you expect a lot of signals (e.g. when using SIGIO), then enabling
287			signal hysteresis can reduce the number of handler invocations
288			considerably, at the cost of two extra syscalls.
289
290			Note that setting the signal to C<SIG_IGN> can have unintended side
291			effects when you fork and exec other programs, as often they do nto expect
292			signals to be ignored by default.
293
294	root	1.2	=item $async->block
295
296	root	1.3	=item $async->unblock
297
298			Sometimes you need a "critical section" of code that will not be
299			interrupted by an Async::Interrupt. This can be implemented by calling C<<
300			$async->block >> before the critical section, and C<< $async->unblock >>
301			afterwards.
302
303	root	1.4	Note that there must be exactly one call of C<unblock> for every previous
304	root	1.3	call to C<block> (i.e. calls can nest).
305
306	root	1.4	Since ensuring this in the presence of exceptions and threads is
307	root	1.3	usually more difficult than you imagine, I recommend using C<<
308			$async->scoped_block >> instead.
309	root	1.2
310	root	1.3	=item $async->scope_block
311
312			This call C<< $async->block >> and installs a handler that is called when
313			the current scope is exited (via an exception, by canceling the Coro
314			thread, by calling last/goto etc.).
315
316			This is the recommended (and fastest) way to implement critical sections.
317	root	1.2
318	root	1.17	=item ($block_func, $block_arg) = $async->scope_block_func
319
320			Returns the address of a function that implements the C<scope_block>
321			functionality.
322
323			It has the following prototype and needs to be passed the specified
324			C<$block_arg>, which is a C<void *> cast to C<IV>:
325
326			void (block_func) (void block_arg)
327
328			An example call would look like:
329
330			block_func (block_arg);
331
332			The function is safe to call only from within the toplevel of a perl XS
333			function and will call C<LEAVE> and C<ENTER> (in this order!).
334
335	root	1.6	=item $async->pipe_enable
336
337			=item $async->pipe_disable
338
339			Enable/disable signalling the pipe when the interrupt occurs (default is
340			enabled). Writing to a pipe is relatively expensive, so it can be disabled
341			when you know you are not waiting for it (for example, with L<EV> you
342			could disable the pipe in a check watcher, and enable it in a prepare
343			watcher).
344
345	root	1.13	Note that currently, while C<pipe_disable> is in effect, no attempt to
346			read from the pipe will be done when handling events. This might change as
347			soon as I realize why this is a mistake.
348
349			=item $fileno = $async->pipe_fileno
350
351			Returns the reading side of the signalling pipe. If no signalling pipe is
352			currently attached to the object, it will dynamically create one.
353
354			Note that the only valid oepration on this file descriptor is to wait
355			until it is readable. The fd might belong currently to a pipe, a tcp
356			socket, or an eventfd, depending on the platform, and is guaranteed to be
357			C<select>able.
358
359	root	1.16	=item $async->pipe_autodrain ($enable)
360
361			Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
362			enabled). When automatic draining is enabled, then Async::Interrupt will
363			automatically clear the pipe. Otherwise the user is responsible for this
364			draining.
365
366			This is useful when you want to share one pipe among many Async::Interrupt
367			objects.
368
369	root	1.13	=item $async->post_fork
370
371			The object will not normally be usable after a fork (as the pipe fd is
372			shared between processes). Calling this method after a fork in the child
373			ensures that the object will work as expected again. It only needs to be
374			called when the async object is used in the child.
375
376			This only works when the pipe was created by Async::Interrupt.
377
378			Async::Interrupt ensures that the reading file descriptor does not change
379			it's value.
380	root	1.6
381	root	1.16	=back
382
383			=head1 THE Async::Interrupt::EventPipe CLASS
384
385			Pipes are the predominent utility to make asynchronous signals
386			synchronous. However, pipes are hard to come by: they don't exist on the
387			broken windows platform, and on GNU/Linux systems, you might want to use
388			an C<eventfd> instead.
389
390			This class creates selectable event pipes in a portable fashion: on
391			windows, it will try to create a tcp socket pair, on GNU/Linux, it will
392			try to create an eventfd and everywhere else it will try to use a normal
393			pipe.
394
395			=over 4
396
397			=item $epipe = new Async::Interrupt::EventPipe
398
399			This creates and returns an eventpipe object. This object is simply a
400			blessed array reference:
401
402			=item ($r_fd, $w_fd) = $epipe->filenos
403
404			Returns the read-side file descriptor and the write-side file descriptor.
405
406			Example: pass an eventpipe object as pipe to the Async::Interrupt
407			constructor, and create an AnyEvent watcher for the read side.
408
409			my $epipe = new Async::Interrupt::EventPipe;
410			my $asy = new Async::Interrupt pipe => [$epipe->filenos];
411			my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
412
413			=item $r_fd = $epipe->fileno
414
415			Return only the reading/listening side.
416
417			=item $epipe->signal
418
419			Write something to the pipe, in a portable fashion.
420
421			=item $epipe->drain
422
423			Drain (empty) the pipe.
424
425			=item $epipe->renew
426
427			Recreates the pipe (useful after a fork). The reading side will not change
428			it's file descriptor number, but the writing side might.
429
430			=back
431
432	root	1.1	=cut
433
434			1;
435
436	root	1.2	=head1 EXAMPLE
437
438	root	1.8	There really should be a complete C/XS example. Bug me about it. Better
439			yet, create one.
440	root	1.2
441			=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
442
443	root	1.8	This module works by "hijacking" SIGKILL, which is guaranteed to always
444			exist, but also cannot be caught, so is always available.
445	root	1.2
446	root	1.8	Basically, this module fakes the occurance of a SIGKILL signal and
447			then intercepts the interpreter handling it. This makes normal signal
448			handling slower (probably unmeasurably, though), but has the advantage
449			of not requiring a special runops function, nor slowing down normal perl
450			execution a bit.
451
452	root	1.13	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
453			modify.
454	root	1.2
455	root	1.1	=head1 AUTHOR
456
457			Marc Lehmann <schmorp@schmorp.de>
458			http://home.schmorp.de/
459
460			=cut
461