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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.6 by root, Sat Jul 11 22:16:50 2009 UTC vs.
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines