| 1 |
NAME |
| 2 |
Async::Interrupt - allow C/XS libraries to interrupt perl asynchronously |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Async::Interrupt; |
| 6 |
|
| 7 |
DESCRIPTION |
| 8 |
This module implements a single feature only of interest to advanced |
| 9 |
perl modules, namely asynchronous interruptions (think "UNIX signals", |
| 10 |
which are very similar). |
| 11 |
|
| 12 |
Sometimes, modules wish to run code asynchronously (in another thread, |
| 13 |
or from a signal handler), and then signal the perl interpreter on |
| 14 |
certain events. One common way is to write some data to a pipe and use |
| 15 |
an event handling toolkit to watch for I/O events. Another way is to |
| 16 |
send a signal. Those methods are slow, and in the case of a pipe, also |
| 17 |
not asynchronous - it won't interrupt a running perl interpreter. |
| 18 |
|
| 19 |
This module implements asynchronous notifications that enable you to |
| 20 |
signal running perl code from another thread, asynchronously, and |
| 21 |
sometimes even without using a single syscall. |
| 22 |
|
| 23 |
USAGE SCENARIOS |
| 24 |
Race-free signal handling |
| 25 |
There seems to be no way to do race-free signal handling in perl: to |
| 26 |
catch a signal, you have to execute Perl code, and between entering |
| 27 |
the interpreter "select" function (or other blocking functions) and |
| 28 |
executing the select syscall is a small but relevant timespan during |
| 29 |
which signals will be queued, but perl signal handlers will not be |
| 30 |
executed and the blocking syscall will not be interrupted. |
| 31 |
|
| 32 |
You can use this module to bind a signal to a callback while at the |
| 33 |
same time activating an event pipe that you can "select" on, fixing |
| 34 |
the race completely. |
| 35 |
|
| 36 |
This can be used to implement the signal handling in event loops, |
| 37 |
e.g. AnyEvent, POE, IO::Async::Loop and so on. |
| 38 |
|
| 39 |
Background threads want speedy reporting |
| 40 |
Assume you want very exact timing, and you can spare an extra cpu |
| 41 |
core for that. Then you can run an extra thread that signals your |
| 42 |
perl interpreter. This means you can get a very exact timing source |
| 43 |
while your perl code is number crunching, without even using a |
| 44 |
syscall to communicate between your threads. |
| 45 |
|
| 46 |
For example the deliantra game server uses a variant of this |
| 47 |
technique to interrupt background processes regularly to send map |
| 48 |
updates to game clients. |
| 49 |
|
| 50 |
Or EV::Loop::Async uses an interrupt object to wake up perl when new |
| 51 |
events have arrived. |
| 52 |
|
| 53 |
IO::AIO and BDB could also use this to speed up result reporting. |
| 54 |
|
| 55 |
Speedy event loop invocation |
| 56 |
One could use this module e.g. in Coro to interrupt a running |
| 57 |
coro-thread and cause it to enter the event loop. |
| 58 |
|
| 59 |
Or one could bind to "SIGIO" and tell some important sockets to send |
| 60 |
this signal, causing the event loop to be entered to reduce network |
| 61 |
latency. |
| 62 |
|
| 63 |
HOW TO USE |
| 64 |
You can use this module by creating an "Async::Interrupt" object for |
| 65 |
each such event source. This object stores a perl and/or a C-level |
| 66 |
callback that is invoked when the "Async::Interrupt" object gets |
| 67 |
signalled. It is executed at the next time the perl interpreter is |
| 68 |
running (i.e. it will interrupt a computation, but not an XS function or |
| 69 |
a syscall). |
| 70 |
|
| 71 |
You can signal the "Async::Interrupt" object either by calling it's |
| 72 |
"->signal" method, or, more commonly, by calling a C function. There is |
| 73 |
also the built-in (POSIX) signal source. |
| 74 |
|
| 75 |
The "->signal_func" returns the address of the C function that is to be |
| 76 |
called (plus an argument to be used during the call). The signalling |
| 77 |
function also takes an integer argument in the range SIG_ATOMIC_MIN to |
| 78 |
SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
| 79 |
|
| 80 |
Since this kind of interruption is fast, but can only interrupt a |
| 81 |
*running* interpreter, there is optional support for signalling a pipe - |
| 82 |
that means you can also wait for the pipe to become readable (e.g. via |
| 83 |
EV or AnyEvent). This, of course, incurs the overhead of a "read" and |
| 84 |
"write" syscall. |
| 85 |
|
| 86 |
USAGE EXAMPLES |
| 87 |
Implementing race-free signal handling |
| 88 |
This example uses a single event pipe for all signals, and one |
| 89 |
Async::Interrupt per signal. This code is actually what the AnyEvent |
| 90 |
module uses itself when Async::Interrupt is available. |
| 91 |
|
| 92 |
First, create the event pipe and hook it into the event loop |
| 93 |
|
| 94 |
$SIGPIPE = new Async::Interrupt::EventPipe; |
| 95 |
$SIGPIPE_W = AnyEvent->io ( |
| 96 |
fh => $SIGPIPE->fileno, |
| 97 |
poll => "r", |
| 98 |
cb => \&_signal_check, # defined later |
| 99 |
); |
| 100 |
|
| 101 |
Then, for each signal to hook, create an Async::Interrupt object. The |
| 102 |
callback just sets a global variable, as we are only interested in |
| 103 |
synchronous signals (i.e. when the event loop polls), which is why the |
| 104 |
pipe draining is not done automatically. |
| 105 |
|
| 106 |
my $interrupt = new Async::Interrupt |
| 107 |
cb => sub { undef $SIGNAL_RECEIVED{$signum} }, |
| 108 |
signal => $signum, |
| 109 |
pipe => [$SIGPIPE->filenos], |
| 110 |
pipe_autodrain => 0, |
| 111 |
; |
| 112 |
|
| 113 |
Finally, the I/O callback for the event pipe handles the signals: |
| 114 |
|
| 115 |
sub _signal_check { |
| 116 |
# drain the pipe first |
| 117 |
$SIGPIPE->drain; |
| 118 |
|
| 119 |
# two loops, just to be sure |
| 120 |
while (%SIGNAL_RECEIVED) { |
| 121 |
for (keys %SIGNAL_RECEIVED) { |
| 122 |
delete $SIGNAL_RECEIVED{$_}; |
| 123 |
warn "signal $_ received\n"; |
| 124 |
} |
| 125 |
} |
| 126 |
} |
| 127 |
|
| 128 |
Interrupt perl from another thread |
| 129 |
This example interrupts the Perl interpreter from another thread, via |
| 130 |
the XS API. This is used by e.g. the EV::Loop::Async module. |
| 131 |
|
| 132 |
On the Perl level, a new loop object (which contains the thread) is |
| 133 |
created, by first calling some XS constructor, querying the C-level |
| 134 |
callback function and feeding that as the "c_cb" into the |
| 135 |
Async::Interrupt constructor: |
| 136 |
|
| 137 |
my $self = XS_thread_constructor; |
| 138 |
my ($c_func, $c_arg) = _c_func $self; # return the c callback |
| 139 |
my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg]; |
| 140 |
|
| 141 |
Then the newly created Interrupt object is queried for the signaling |
| 142 |
function that the newly created thread should call, and this is in turn |
| 143 |
told to the thread object: |
| 144 |
|
| 145 |
_attach $self, $asy->signal_func; |
| 146 |
|
| 147 |
So to repeat: first the XS object is created, then it is queried for the |
| 148 |
callback that should be called when the Interrupt object gets signalled. |
| 149 |
|
| 150 |
Then the interrupt object is queried for the callback function that the |
| 151 |
thread should call to signal the Interrupt object, and this callback is |
| 152 |
then attached to the thread. |
| 153 |
|
| 154 |
You have to be careful that your new thread is not signalling before the |
| 155 |
signal function was configured, for example by starting the background |
| 156 |
thread only within "_attach". |
| 157 |
|
| 158 |
That concludes the Perl part. |
| 159 |
|
| 160 |
The XS part consists of the actual constructor which creates a thread, |
| 161 |
which is not relevant for this example, and two functions, "_c_func", |
| 162 |
which returns the Perl-side callback, and "_attach", which configures |
| 163 |
the signalling functioon that is safe toc all from another thread. For |
| 164 |
simplicity, we will use global variables to store the functions, |
| 165 |
normally you would somehow attach them to $self. |
| 166 |
|
| 167 |
The "c_func" simply returns the address of a static function and |
| 168 |
arranges for the object pointed to by $self to be passed to it, as an |
| 169 |
integer: |
| 170 |
|
| 171 |
void |
| 172 |
_c_func (SV *loop) |
| 173 |
PPCODE: |
| 174 |
EXTEND (SP, 2); |
| 175 |
PUSHs (sv_2mortal (newSViv (PTR2IV (c_func)))); |
| 176 |
PUSHs (sv_2mortal (newSViv (SvRV (loop)))); |
| 177 |
|
| 178 |
This would be the callback (since it runs in a normal Perl context, it |
| 179 |
is permissible to manipulate Perl values): |
| 180 |
|
| 181 |
static void |
| 182 |
c_func (pTHX_ void *loop_, int value) |
| 183 |
{ |
| 184 |
SV *loop_object = (SV *)loop_; |
| 185 |
... |
| 186 |
} |
| 187 |
|
| 188 |
And this attaches the signalling callback: |
| 189 |
|
| 190 |
static void (*my_sig_func) (void *signal_arg, int value); |
| 191 |
static void *my_sig_arg; |
| 192 |
|
| 193 |
void |
| 194 |
_attach (SV *loop_, IV sig_func, void *sig_arg) |
| 195 |
CODE: |
| 196 |
{ |
| 197 |
my_sig_func = sig_func; |
| 198 |
my_sig_arg = sig_arg; |
| 199 |
|
| 200 |
/* now run the thread */ |
| 201 |
thread_create (&u->tid, l_run, 0); |
| 202 |
} |
| 203 |
|
| 204 |
And "l_run" (the background thread) would eventually call the signaling |
| 205 |
function: |
| 206 |
|
| 207 |
my_sig_func (my_sig_arg, 0); |
| 208 |
|
| 209 |
You can have a look at EV::Loop::Async for an actual example using |
| 210 |
intra-thread communication, locking and so on. |
| 211 |
|
| 212 |
THE Async::Interrupt CLASS |
| 213 |
$async = new Async::Interrupt key => value... |
| 214 |
Creates a new Async::Interrupt object. You may only use async |
| 215 |
notifications on this object while it exists, so you need to keep a |
| 216 |
reference to it at all times while it is used. |
| 217 |
|
| 218 |
Optional constructor arguments include (normally you would specify |
| 219 |
at least one of "cb" or "c_cb"). |
| 220 |
|
| 221 |
cb => $coderef->($value) |
| 222 |
Registers a perl callback to be invoked whenever the async |
| 223 |
interrupt is signalled. |
| 224 |
|
| 225 |
Note that, since this callback can be invoked at basically any |
| 226 |
time, it must not modify any well-known global variables such as |
| 227 |
$/ without restoring them again before returning. |
| 228 |
|
| 229 |
The exceptions are $! and $@, which are saved and restored by |
| 230 |
Async::Interrupt. |
| 231 |
|
| 232 |
If the callback should throw an exception, then it will be |
| 233 |
caught, and $Async::Interrupt::DIED will be called with $@ |
| 234 |
containing the exception. The default will simply "warn" about |
| 235 |
the message and continue. |
| 236 |
|
| 237 |
c_cb => [$c_func, $c_arg] |
| 238 |
Registers a C callback the be invoked whenever the async |
| 239 |
interrupt is signalled. |
| 240 |
|
| 241 |
The C callback must have the following prototype: |
| 242 |
|
| 243 |
void c_func (pTHX_ void *c_arg, int value); |
| 244 |
|
| 245 |
Both $c_func and $c_arg must be specified as integers/IVs, and |
| 246 |
$value is the "value" passed to some earlier call to either |
| 247 |
$signal or the "signal_func" function. |
| 248 |
|
| 249 |
Note that, because the callback can be invoked at almost any |
| 250 |
time, you have to be careful at saving and restoring global |
| 251 |
variables that Perl might use (the exception is "errno", which |
| 252 |
is saved and restored by Async::Interrupt). The callback itself |
| 253 |
runs as part of the perl context, so you can call any perl |
| 254 |
functions and modify any perl data structures (in which case the |
| 255 |
requirements set out for "cb" apply as well). |
| 256 |
|
| 257 |
var => $scalar_ref |
| 258 |
When specified, then the given argument must be a reference to a |
| 259 |
scalar. The scalar will be set to 0 initially. Signalling the |
| 260 |
interrupt object will set it to the passed value, handling the |
| 261 |
interrupt will reset it to 0 again. |
| 262 |
|
| 263 |
Note that the only thing you are legally allowed to do is to is |
| 264 |
to check the variable in a boolean or integer context (e.g. |
| 265 |
comparing it with a string, or printing it, will *destroy* it |
| 266 |
and might cause your program to crash or worse). |
| 267 |
|
| 268 |
signal => $signame_or_value |
| 269 |
When this parameter is specified, then the Async::Interrupt will |
| 270 |
hook the given signal, that is, it will effectively call |
| 271 |
"->signal (0)" each time the given signal is caught by the |
| 272 |
process. |
| 273 |
|
| 274 |
Only one async can hook a given signal, and the signal will be |
| 275 |
restored to defaults when the Async::Interrupt object gets |
| 276 |
destroyed. |
| 277 |
|
| 278 |
signal_hysteresis => $boolean |
| 279 |
Sets the initial signal hysteresis state, see the |
| 280 |
"signal_hysteresis" method, below. |
| 281 |
|
| 282 |
pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
| 283 |
Specifies two file descriptors (or file handles) that should be |
| 284 |
signalled whenever the async interrupt is signalled. This means |
| 285 |
a single octet will be written to it, and before the callback is |
| 286 |
being invoked, it will be read again. Due to races, it is |
| 287 |
unlikely but possible that multiple octets are written. It is |
| 288 |
required that the file handles are both in nonblocking mode. |
| 289 |
|
| 290 |
The object will keep a reference to the file handles. |
| 291 |
|
| 292 |
This can be used to ensure that async notifications will |
| 293 |
interrupt event frameworks as well. |
| 294 |
|
| 295 |
Note that "Async::Interrupt" will create a suitable signal fd |
| 296 |
automatically when your program requests one, so you don't have |
| 297 |
to specify this argument when all you want is an extra file |
| 298 |
descriptor to watch. |
| 299 |
|
| 300 |
If you want to share a single event pipe between multiple |
| 301 |
Async::Interrupt objects, you can use the |
| 302 |
"Async::Interrupt::EventPipe" class to manage those. |
| 303 |
|
| 304 |
pipe_autodrain => $boolean |
| 305 |
Sets the initial autodrain state, see the "pipe_autodrain" |
| 306 |
method, below. |
| 307 |
|
| 308 |
($signal_func, $signal_arg) = $async->signal_func |
| 309 |
Returns the address of a function to call asynchronously. The |
| 310 |
function has the following prototype and needs to be passed the |
| 311 |
specified $signal_arg, which is a "void *" cast to "IV": |
| 312 |
|
| 313 |
void (*signal_func) (void *signal_arg, int value) |
| 314 |
|
| 315 |
An example call would look like: |
| 316 |
|
| 317 |
signal_func (signal_arg, 0); |
| 318 |
|
| 319 |
The function is safe to call from within signal and thread contexts, |
| 320 |
at any time. The specified "value" is passed to both C and Perl |
| 321 |
callback. |
| 322 |
|
| 323 |
$value must be in the valid range for a "sig_atomic_t", except 0 |
| 324 |
(1..127 is portable). |
| 325 |
|
| 326 |
If the function is called while the Async::Interrupt object is |
| 327 |
already signaled but before the callbacks are being executed, then |
| 328 |
the stored "value" is either the old or the new one. Due to the |
| 329 |
asynchronous nature of the code, the "value" can even be passed to |
| 330 |
two consecutive invocations of the callback. |
| 331 |
|
| 332 |
$address = $async->c_var |
| 333 |
Returns the address (cast to IV) of an "IV" variable. The variable |
| 334 |
is set to 0 initially and gets set to the passed value whenever the |
| 335 |
object gets signalled, and reset to 0 once the interrupt has been |
| 336 |
handled. |
| 337 |
|
| 338 |
Note that it is often beneficial to just call "PERL_ASYNC_CHECK ()" |
| 339 |
to handle any interrupts. |
| 340 |
|
| 341 |
Example: call some XS function to store the address, then show C |
| 342 |
code waiting for it. |
| 343 |
|
| 344 |
my_xs_func $async->c_var; |
| 345 |
|
| 346 |
static IV *valuep; |
| 347 |
|
| 348 |
void |
| 349 |
my_xs_func (void *addr) |
| 350 |
CODE: |
| 351 |
valuep = (IV *)addr; |
| 352 |
|
| 353 |
// code in a loop, waiting |
| 354 |
while (!*valuep) |
| 355 |
; // do something |
| 356 |
|
| 357 |
$async->signal ($value=1) |
| 358 |
This signals the given async object from Perl code. Semi-obviously, |
| 359 |
this will instantly trigger the callback invocation (it does not, as |
| 360 |
the name might imply, do anything with POSIX signals). |
| 361 |
|
| 362 |
$value must be in the valid range for a "sig_atomic_t", except 0 |
| 363 |
(1..127 is portable). |
| 364 |
|
| 365 |
$async->handle |
| 366 |
Calls the callback if the object is pending. |
| 367 |
|
| 368 |
This method does not need to be called normally, as it will be |
| 369 |
invoked automatically. However, it can be used to force handling of |
| 370 |
outstanding interrupts while the object is blocked. |
| 371 |
|
| 372 |
One reason why one might want to do that is when you want to switch |
| 373 |
from asynchronous interruptions to synchronous one, using e.g. an |
| 374 |
event loop. To do that, one would first "$async->block" the |
| 375 |
interrupt object, then register a read watcher on the "pipe_fileno" |
| 376 |
that calls "$async->handle". |
| 377 |
|
| 378 |
This disables asynchronous interruptions, but ensures that |
| 379 |
interrupts are handled by the event loop. |
| 380 |
|
| 381 |
$async->signal_hysteresis ($enable) |
| 382 |
Enables or disables signal hysteresis (default: disabled). If a |
| 383 |
POSIX signal is used as a signal source for the interrupt object, |
| 384 |
then enabling signal hysteresis causes Async::Interrupt to reset the |
| 385 |
signal action to "SIG_IGN" in the signal handler and restore it just |
| 386 |
before handling the interruption. |
| 387 |
|
| 388 |
When you expect a lot of signals (e.g. when using SIGIO), then |
| 389 |
enabling signal hysteresis can reduce the number of handler |
| 390 |
invocations considerably, at the cost of two extra syscalls. |
| 391 |
|
| 392 |
Note that setting the signal to "SIG_IGN" can have unintended side |
| 393 |
effects when you fork and exec other programs, as often they do not |
| 394 |
expect signals to be ignored by default. |
| 395 |
|
| 396 |
$async->block |
| 397 |
$async->unblock |
| 398 |
Sometimes you need a "critical section" of code that will not be |
| 399 |
interrupted by an Async::Interrupt. This can be implemented by |
| 400 |
calling "$async->block" before the critical section, and |
| 401 |
"$async->unblock" afterwards. |
| 402 |
|
| 403 |
Note that there must be exactly one call of "unblock" for every |
| 404 |
previous call to "block" (i.e. calls can nest). |
| 405 |
|
| 406 |
Since ensuring this in the presence of exceptions and threads is |
| 407 |
usually more difficult than you imagine, I recommend using |
| 408 |
"$async->scoped_block" instead. |
| 409 |
|
| 410 |
$async->scope_block |
| 411 |
This call "$async->block" and installs a handler that is called when |
| 412 |
the current scope is exited (via an exception, by canceling the Coro |
| 413 |
thread, by calling last/goto etc.). |
| 414 |
|
| 415 |
This is the recommended (and fastest) way to implement critical |
| 416 |
sections. |
| 417 |
|
| 418 |
($block_func, $block_arg) = $async->scope_block_func |
| 419 |
Returns the address of a function that implements the "scope_block" |
| 420 |
functionality. |
| 421 |
|
| 422 |
It has the following prototype and needs to be passed the specified |
| 423 |
$block_arg, which is a "void *" cast to "IV": |
| 424 |
|
| 425 |
void (*block_func) (void *block_arg) |
| 426 |
|
| 427 |
An example call would look like: |
| 428 |
|
| 429 |
block_func (block_arg); |
| 430 |
|
| 431 |
The function is safe to call only from within the toplevel of a perl |
| 432 |
XS function and will call "LEAVE" and "ENTER" (in this order!). |
| 433 |
|
| 434 |
$async->pipe_enable |
| 435 |
$async->pipe_disable |
| 436 |
Enable/disable signalling the pipe when the interrupt occurs |
| 437 |
(default is enabled). Writing to a pipe is relatively expensive, so |
| 438 |
it can be disabled when you know you are not waiting for it (for |
| 439 |
example, with EV you could disable the pipe in a check watcher, and |
| 440 |
enable it in a prepare watcher). |
| 441 |
|
| 442 |
Note that currently, while "pipe_disable" is in effect, no attempt |
| 443 |
to read from the pipe will be done when handling events. This might |
| 444 |
change as soon as I realize why this is a mistake. |
| 445 |
|
| 446 |
$fileno = $async->pipe_fileno |
| 447 |
Returns the reading side of the signalling pipe. If no signalling |
| 448 |
pipe is currently attached to the object, it will dynamically create |
| 449 |
one. |
| 450 |
|
| 451 |
Note that the only valid operation on this file descriptor is to |
| 452 |
wait until it is readable. The fd might belong currently to a pipe, |
| 453 |
a tcp socket, or an eventfd, depending on the platform, and is |
| 454 |
guaranteed to be "select"able. |
| 455 |
|
| 456 |
$async->pipe_autodrain ($enable) |
| 457 |
Enables (1) or disables (0) automatic draining of the pipe (default: |
| 458 |
enabled). When automatic draining is enabled, then Async::Interrupt |
| 459 |
will automatically clear the pipe. Otherwise the user is responsible |
| 460 |
for this draining. |
| 461 |
|
| 462 |
This is useful when you want to share one pipe among many |
| 463 |
Async::Interrupt objects. |
| 464 |
|
| 465 |
$async->pipe_drain |
| 466 |
Drains the pipe manually, for example, when autodrain is disabled. |
| 467 |
Does nothing when no pipe is enabled. |
| 468 |
|
| 469 |
$async->post_fork |
| 470 |
The object will not normally be usable after a fork (as the pipe fd |
| 471 |
is shared between processes). Calling this method after a fork in |
| 472 |
the child ensures that the object will work as expected again. It |
| 473 |
only needs to be called when the async object is used in the child. |
| 474 |
|
| 475 |
This only works when the pipe was created by Async::Interrupt. |
| 476 |
|
| 477 |
Async::Interrupt ensures that the reading file descriptor does not |
| 478 |
change it's value. |
| 479 |
|
| 480 |
$signum = Async::Interrupt::sig2num $signame_or_number |
| 481 |
$signame = Async::Interrupt::sig2name $signame_or_number |
| 482 |
These two convenience functions simply convert a signal name or |
| 483 |
number to the corresponding name or number. They are not used by |
| 484 |
this module and exist just because perl doesn't have a nice way to |
| 485 |
do this on its own. |
| 486 |
|
| 487 |
They will return "undef" on illegal names or numbers. |
| 488 |
|
| 489 |
THE Async::Interrupt::EventPipe CLASS |
| 490 |
Pipes are the predominant utility to make asynchronous signals |
| 491 |
synchronous. However, pipes are hard to come by: they don't exist on the |
| 492 |
broken windows platform, and on GNU/Linux systems, you might want to use |
| 493 |
an "eventfd" instead. |
| 494 |
|
| 495 |
This class creates selectable event pipes in a portable fashion: on |
| 496 |
windows, it will try to create a tcp socket pair, on GNU/Linux, it will |
| 497 |
try to create an eventfd and everywhere else it will try to use a normal |
| 498 |
pipe. |
| 499 |
|
| 500 |
$epipe = new Async::Interrupt::EventPipe |
| 501 |
This creates and returns an eventpipe object. This object is simply |
| 502 |
a blessed array reference: |
| 503 |
|
| 504 |
($r_fd, $w_fd) = $epipe->filenos |
| 505 |
Returns the read-side file descriptor and the write-side file |
| 506 |
descriptor. |
| 507 |
|
| 508 |
Example: pass an eventpipe object as pipe to the Async::Interrupt |
| 509 |
constructor, and create an AnyEvent watcher for the read side. |
| 510 |
|
| 511 |
my $epipe = new Async::Interrupt::EventPipe; |
| 512 |
my $asy = new Async::Interrupt pipe => [$epipe->filenos]; |
| 513 |
my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { }); |
| 514 |
|
| 515 |
$r_fd = $epipe->fileno |
| 516 |
Return only the reading/listening side. |
| 517 |
|
| 518 |
$epipe->signal |
| 519 |
Write something to the pipe, in a portable fashion. |
| 520 |
|
| 521 |
$epipe->drain |
| 522 |
Drain (empty) the pipe. |
| 523 |
|
| 524 |
($c_func, $c_arg) = $epipe->signal_func |
| 525 |
($c_func, $c_arg) = $epipe->drain_func |
| 526 |
These two methods returns a function pointer and "void *" argument |
| 527 |
that can be called to have the effect of "$epipe->signal" or |
| 528 |
"$epipe->drain", respectively, on the XS level. |
| 529 |
|
| 530 |
They both have the following prototype and need to be passed their |
| 531 |
$c_arg, which is a "void *" cast to an "IV": |
| 532 |
|
| 533 |
void (*c_func) (void *c_arg) |
| 534 |
|
| 535 |
An example call would look like: |
| 536 |
|
| 537 |
c_func (c_arg); |
| 538 |
|
| 539 |
$epipe->renew |
| 540 |
Recreates the pipe (usually required in the child after a fork). The |
| 541 |
reading side will not change it's file descriptor number, but the |
| 542 |
writing side might. |
| 543 |
|
| 544 |
$epipe->wait |
| 545 |
This method blocks the process until there are events on the pipe. |
| 546 |
This is not a very event-based or ncie way of usign an event pipe, |
| 547 |
but it can be occasionally useful. |
| 548 |
|
| 549 |
IMPLEMENTATION DETAILS AND LIMITATIONS |
| 550 |
This module works by "hijacking" SIGKILL, which is guaranteed to always |
| 551 |
exist, but also cannot be caught, so is always available. |
| 552 |
|
| 553 |
Basically, this module fakes the occurence of a SIGKILL signal and then |
| 554 |
intercepts the interpreter handling it. This makes normal signal |
| 555 |
handling slower (probably unmeasurably, though), but has the advantage |
| 556 |
of not requiring a special runops function, nor slowing down normal perl |
| 557 |
execution a bit. |
| 558 |
|
| 559 |
It assumes that "sig_atomic_t", "int" and "IV" are all async-safe to |
| 560 |
modify. |
| 561 |
|
| 562 |
AUTHOR |
| 563 |
Marc Lehmann <[email protected]> |
| 564 |
http://home.schmorp.de/ |
| 565 |
|