Debian Codegraph @

README

raw
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