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.12 by root, Tue Jul 14 19:51:24 2009 UTC vs.
Revision 1.36 by root, Tue Apr 17 19:21:28 2018 UTC

53 53
54For example the deliantra game server uses a variant of this technique 54For example the deliantra game server uses a variant of this technique
55to interrupt background processes regularly to send map updates to game 55to interrupt background processes regularly to send map updates to game
56clients. 56clients.
57 57
58Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
59events have arrived.
60
58L<IO::AIO> and L<BDB> could also use this to speed up result reporting. 61L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
59 62
60=item Speedy event loop invocation 63=item Speedy event loop invocation
61 64
62One could use this module e.g. in L<Coro> to interrupt a running coro-thread 65One could use this module e.g. in L<Coro> to interrupt a running coro-thread
88I<running> interpreter, there is optional support for signalling a pipe 91I<running> interpreter, there is optional support for signalling a pipe
89- that means you can also wait for the pipe to become readable (e.g. via 92- that means you can also wait for the pipe to become readable (e.g. via
90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> 93L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91and C<write> syscall. 94and C<write> syscall.
92 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
145On the Perl level, a new loop object (which contains the thread)
146is created, by first calling some XS constructor, querying the
147C-level callback function and feeding that as the C<c_cb> into the
148Async::Interrupt constructor:
149
150 my $self = XS_thread_constructor;
151 my ($c_func, $c_arg) = _c_func $self; # return the c callback
152 my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg];
153
154Then the newly created Interrupt object is queried for the signaling
155function that the newly created thread should call, and this is in turn
156told to the thread object:
157
158 _attach $self, $asy->signal_func;
159
160So to repeat: first the XS object is created, then it is queried for the
161callback that should be called when the Interrupt object gets signalled.
162
163Then the interrupt object is queried for the callback fucntion that the
164thread should call to signal the Interrupt object, and this callback is
165then attached to the thread.
166
167You have to be careful that your new thread is not signalling before the
168signal function was configured, for example by starting the background
169thread only within C<_attach>.
170
171That concludes the Perl part.
172
173The XS part consists of the actual constructor which creates a thread,
174which is not relevant for this example, and two functions, C<_c_func>,
175which returns the Perl-side callback, and C<_attach>, which configures
176the signalling functioon that is safe toc all from another thread. For
177simplicity, we will use global variables to store the functions, normally
178you would somehow attach them to C<$self>.
179
180The C<c_func> simply returns the address of a static function and arranges
181for the object pointed to by C<$self> to be passed to it, as an integer:
182
183 void
184 _c_func (SV *loop)
185 PPCODE:
186 EXTEND (SP, 2);
187 PUSHs (sv_2mortal (newSViv (PTR2IV (c_func))));
188 PUSHs (sv_2mortal (newSViv (SvRV (loop))));
189
190This would be the callback (since it runs in a normal Perl context, it is
191permissible to manipulate Perl values):
192
193 static void
194 c_func (pTHX_ void *loop_, int value)
195 {
196 SV *loop_object = (SV *)loop_;
197 ...
198 }
199
200And this attaches the signalling callback:
201
202 static void (*my_sig_func) (void *signal_arg, int value);
203 static void *my_sig_arg;
204
205 void
206 _attach (SV *loop_, IV sig_func, void *sig_arg)
207 CODE:
208 {
209 my_sig_func = sig_func;
210 my_sig_arg = sig_arg;
211
212 /* now run the thread */
213 thread_create (&u->tid, l_run, 0);
214 }
215
216And C<l_run> (the background thread) would eventually call the signaling
217function:
218
219 my_sig_func (my_sig_arg, 0);
220
221You can have a look at L<EV::Loop::Async> for an actual example using
222intra-thread communication, locking and so on.
223
224
225=head1 THE Async::Interrupt CLASS
226
93=over 4 227=over 4
94 228
95=cut 229=cut
96 230
97package Async::Interrupt; 231package Async::Interrupt;
98 232
99use common::sense; 233use common::sense;
100 234
101BEGIN { 235BEGIN {
102 # the next line forces initialisation of internal 236 # the next line forces initialisation of internal
103 # signal handling # variables 237 # signal handling variables, otherwise, PL_sig_pending
238 # etc. might be null pointers.
104 $SIG{KILL} = sub { }; 239 $SIG{KILL} = sub { };
105 240
106 our $VERSION = '0.042'; 241 our $VERSION = 1.23;
107 242
108 require XSLoader; 243 require XSLoader;
109 XSLoader::load ("Async::Interrupt", $VERSION); 244 XSLoader::load ("Async::Interrupt", $VERSION);
110} 245}
111 246
134The exceptions are C<$!> and C<$@>, which are saved and restored by 269The exceptions are C<$!> and C<$@>, which are saved and restored by
135Async::Interrupt. 270Async::Interrupt.
136 271
137If the callback should throw an exception, then it will be caught, 272If the callback should throw an exception, then it will be caught,
138and C<$Async::Interrupt::DIED> will be called with C<$@> containing 273and C<$Async::Interrupt::DIED> will be called with C<$@> containing
139the exception. The default will simply C<warn> about the message and 274the exception. The default will simply C<warn> about the message and
140continue. 275continue.
141 276
142=item c_cb => [$c_func, $c_arg] 277=item c_cb => [$c_func, $c_arg]
143 278
144Registers a C callback the be invoked whenever the async interrupt is 279Registers a C callback the be invoked whenever the async interrupt is
157might use (the exception is C<errno>, which is saved and restored by 292might use (the exception is C<errno>, which is saved and restored by
158Async::Interrupt). The callback itself runs as part of the perl context, 293Async::Interrupt). The callback itself runs as part of the perl context,
159so you can call any perl functions and modify any perl data structures (in 294so you can call any perl functions and modify any perl data structures (in
160which case the requirements set out for C<cb> apply as well). 295which case the requirements set out for C<cb> apply as well).
161 296
297=item var => $scalar_ref
298
299When specified, then the given argument must be a reference to a
300scalar. The scalar will be set to C<0> initially. Signalling the interrupt
301object will set it to the passed value, handling the interrupt will reset
302it to C<0> again.
303
304Note that the only thing you are legally allowed to do is to is to check
305the variable in a boolean or integer context (e.g. comparing it with a
306string, or printing it, will I<destroy> it and might cause your program to
307crash or worse).
308
162=item signal => $signame_or_value 309=item signal => $signame_or_value
163 310
164When this parameter is specified, then the Async::Interrupt will hook the 311When this parameter is specified, then the Async::Interrupt will hook the
165given signal, that is, it will effectively call C<< ->signal (0) >> each time 312given signal, that is, it will effectively call C<< ->signal (0) >> each time
166the given signal is caught by the process. 313the given signal is caught by the process.
167 314
168Only one async can hook a given signal, and the signal will be restored to 315Only one async can hook a given signal, and the signal will be restored to
169defaults when the Async::Interrupt object gets destroyed. 316defaults when the Async::Interrupt object gets destroyed.
317
318=item signal_hysteresis => $boolean
319
320Sets the initial signal hysteresis state, see the C<signal_hysteresis>
321method, below.
170 322
171=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 323=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
172 324
173Specifies two file descriptors (or file handles) that should be signalled 325Specifies two file descriptors (or file handles) that should be signalled
174whenever the async interrupt is signalled. This means a single octet will 326whenever the async interrupt is signalled. This means a single octet will
175be written to it, and before the callback is being invoked, it will be 327be written to it, and before the callback is being invoked, it will be
176read again. Due to races, it is unlikely but possible that multiple octets 328read again. Due to races, it is unlikely but possible that multiple octets
177are written. It is required that the file handles are both in nonblocking 329are written. It is required that the file handles are both in nonblocking
178mode. 330mode.
179 331
180You can get a portable pipe and set non-blocking mode portably by using
181e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
182
183It is also possible to pass in a linux eventfd as both read and write
184handle (which is faster than a pipe).
185
186The object will keep a reference to the file handles. 332The object will keep a reference to the file handles.
187 333
188This can be used to ensure that async notifications will interrupt event 334This can be used to ensure that async notifications will interrupt event
189frameworks as well. 335frameworks as well.
190 336
337Note that C<Async::Interrupt> will create a suitable signal fd
338automatically when your program requests one, so you don't have to specify
339this argument when all you want is an extra file descriptor to watch.
340
341If you want to share a single event pipe between multiple Async::Interrupt
342objects, you can use the C<Async::Interrupt::EventPipe> class to manage
343those.
344
345=item pipe_autodrain => $boolean
346
347Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
348
191=back 349=back
192 350
193=cut 351=cut
194 352
195sub new { 353sub new {
196 my ($class, %arg) = @_; 354 my ($class, %arg) = @_;
197 355
198 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class 356 my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
357
358 # urgs, reminds me of Event
359 for my $attr (qw(pipe_autodrain signal_hysteresis)) {
360 $self->$attr ($arg{$attr}) if exists $arg{$attr};
361 }
362
363 $self
199} 364}
200 365
201=item ($signal_func, $signal_arg) = $async->signal_func 366=item ($signal_func, $signal_arg) = $async->signal_func
202 367
203Returns the address of a function to call asynchronously. The function has 368Returns the address of a function to call asynchronously. The function
204the following prototype and needs to be passed the specified C<$c_arg>, 369has the following prototype and needs to be passed the specified
205which is a C<void *> cast to C<IV>: 370C<$signal_arg>, which is a C<void *> cast to C<IV>:
206 371
207 void (*signal_func) (void *signal_arg, int value) 372 void (*signal_func) (void *signal_arg, int value)
208 373
209An example call would look like: 374An example call would look like:
210 375
211 signal_func (signal_arg, 0); 376 signal_func (signal_arg, 0);
212 377
213The function is safe to call from within signal and thread contexts, at 378The function is safe to call from within signal and thread contexts, at
214any time. The specified C<value> is passed to both C and Perl callback. 379any time. The specified C<value> is passed to both C and Perl callback.
215 380
216C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is 381C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
217portable). 382(1..127 is portable).
218 383
219If the function is called while the Async::Interrupt object is already 384If the function is called while the Async::Interrupt object is already
220signaled but before the callbacks are being executed, then the stored 385signaled but before the callbacks are being executed, then the stored
221C<value> is either the old or the new one. Due to the asynchronous 386C<value> is either the old or the new one. Due to the asynchronous
222nature of the code, the C<value> can even be passed to two consecutive 387nature of the code, the C<value> can even be passed to two consecutive
223invocations of the callback. 388invocations of the callback.
224 389
390=item $address = $async->c_var
391
392Returns the address (cast to IV) of an C<IV> variable. The variable is set
393to C<0> initially and gets set to the passed value whenever the object
394gets signalled, and reset to C<0> once the interrupt has been handled.
395
396Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
397handle any interrupts.
398
399Example: call some XS function to store the address, then show C code
400waiting for it.
401
402 my_xs_func $async->c_var;
403
404 static IV *valuep;
405
406 void
407 my_xs_func (void *addr)
408 CODE:
409 valuep = (IV *)addr;
410
411 // code in a loop, waiting
412 while (!*valuep)
413 ; // do something
414
225=item $async->signal ($value=0) 415=item $async->signal ($value=1)
226 416
227This signals the given async object from Perl code. Semi-obviously, this 417This signals the given async object from Perl code. Semi-obviously, this
228will instantly trigger the callback invocation. 418will instantly trigger the callback invocation (it does not, as the name
419might imply, do anything with POSIX signals).
229 420
230C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is 421C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
231portable). 422(1..127 is portable).
423
424=item $async->handle
425
426Calls the callback if the object is pending.
427
428This method does not need to be called normally, as it will be invoked
429automatically. However, it can be used to force handling of outstanding
430interrupts while the object is blocked.
431
432One reason why one might want to do that is when you want to switch
433from asynchronous interruptions to synchronous one, using e.g. an event
434loop. To do that, one would first C<< $async->block >> the interrupt
435object, then register a read watcher on the C<pipe_fileno> that calls C<<
436$async->handle >>.
437
438This disables asynchronous interruptions, but ensures that interrupts are
439handled by the event loop.
440
441=item $async->signal_hysteresis ($enable)
442
443Enables or disables signal hysteresis (default: disabled). If a POSIX
444signal is used as a signal source for the interrupt object, then enabling
445signal hysteresis causes Async::Interrupt to reset the signal action to
446C<SIG_IGN> in the signal handler and restore it just before handling the
447interruption.
448
449When you expect a lot of signals (e.g. when using SIGIO), then enabling
450signal hysteresis can reduce the number of handler invocations
451considerably, at the cost of two extra syscalls.
452
453Note that setting the signal to C<SIG_IGN> can have unintended side
454effects when you fork and exec other programs, as often they do not expect
455signals to be ignored by default.
232 456
233=item $async->block 457=item $async->block
234 458
235=item $async->unblock 459=item $async->unblock
236 460
251This call C<< $async->block >> and installs a handler that is called when 475This call C<< $async->block >> and installs a handler that is called when
252the current scope is exited (via an exception, by canceling the Coro 476the current scope is exited (via an exception, by canceling the Coro
253thread, by calling last/goto etc.). 477thread, by calling last/goto etc.).
254 478
255This is the recommended (and fastest) way to implement critical sections. 479This is the recommended (and fastest) way to implement critical sections.
480
481=item ($block_func, $block_arg) = $async->scope_block_func
482
483Returns the address of a function that implements the C<scope_block>
484functionality.
485
486It has the following prototype and needs to be passed the specified
487C<$block_arg>, which is a C<void *> cast to C<IV>:
488
489 void (*block_func) (void *block_arg)
490
491An example call would look like:
492
493 block_func (block_arg);
494
495The function is safe to call only from within the toplevel of a perl XS
496function and will call C<LEAVE> and C<ENTER> (in this order!).
256 497
257=item $async->pipe_enable 498=item $async->pipe_enable
258 499
259=item $async->pipe_disable 500=item $async->pipe_disable
260 501
262enabled). Writing to a pipe is relatively expensive, so it can be disabled 503enabled). Writing to a pipe is relatively expensive, so it can be disabled
263when you know you are not waiting for it (for example, with L<EV> you 504when you know you are not waiting for it (for example, with L<EV> you
264could disable the pipe in a check watcher, and enable it in a prepare 505could disable the pipe in a check watcher, and enable it in a prepare
265watcher). 506watcher).
266 507
267Note that when C<fd_disable> is in effect, no attempt to read from the 508Note that currently, while C<pipe_disable> is in effect, no attempt to
268pipe will be done. 509read from the pipe will be done when handling events. This might change as
510soon as I realize why this is a mistake.
511
512=item $fileno = $async->pipe_fileno
513
514Returns the reading side of the signalling pipe. If no signalling pipe is
515currently attached to the object, it will dynamically create one.
516
517Note that the only valid operation on this file descriptor is to wait
518until it is readable. The fd might belong currently to a pipe, a tcp
519socket, or an eventfd, depending on the platform, and is guaranteed to be
520C<select>able.
521
522=item $async->pipe_autodrain ($enable)
523
524Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
525enabled). When automatic draining is enabled, then Async::Interrupt will
526automatically clear the pipe. Otherwise the user is responsible for this
527draining.
528
529This is useful when you want to share one pipe among many Async::Interrupt
530objects.
531
532=item $async->pipe_drain
533
534Drains the pipe manually, for example, when autodrain is disabled. Does
535nothing when no pipe is enabled.
536
537=item $async->post_fork
538
539The object will not normally be usable after a fork (as the pipe fd is
540shared between processes). Calling this method after a fork in the child
541ensures that the object will work as expected again. It only needs to be
542called when the async object is used in the child.
543
544This only works when the pipe was created by Async::Interrupt.
545
546Async::Interrupt ensures that the reading file descriptor does not change
547it's value.
548
549=item $signum = Async::Interrupt::sig2num $signame_or_number
550
551=item $signame = Async::Interrupt::sig2name $signame_or_number
552
553These two convenience functions simply convert a signal name or number to
554the corresponding name or number. They are not used by this module and
555exist just because perl doesn't have a nice way to do this on its own.
556
557They will return C<undef> on illegal names or numbers.
558
559=back
560
561=head1 THE Async::Interrupt::EventPipe CLASS
562
563Pipes are the predominant utility to make asynchronous signals
564synchronous. However, pipes are hard to come by: they don't exist on the
565broken windows platform, and on GNU/Linux systems, you might want to use
566an C<eventfd> instead.
567
568This class creates selectable event pipes in a portable fashion: on
569windows, it will try to create a tcp socket pair, on GNU/Linux, it will
570try to create an eventfd and everywhere else it will try to use a normal
571pipe.
572
573=over 4
574
575=item $epipe = new Async::Interrupt::EventPipe
576
577This creates and returns an eventpipe object. This object is simply a
578blessed array reference:
579
580=item ($r_fd, $w_fd) = $epipe->filenos
581
582Returns the read-side file descriptor and the write-side file descriptor.
583
584Example: pass an eventpipe object as pipe to the Async::Interrupt
585constructor, and create an AnyEvent watcher for the read side.
586
587 my $epipe = new Async::Interrupt::EventPipe;
588 my $asy = new Async::Interrupt pipe => [$epipe->filenos];
589 my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
590
591=item $r_fd = $epipe->fileno
592
593Return only the reading/listening side.
594
595=item $epipe->signal
596
597Write something to the pipe, in a portable fashion.
598
599=item $epipe->drain
600
601Drain (empty) the pipe.
602
603=item ($c_func, $c_arg) = $epipe->signal_func
604
605=item ($c_func, $c_arg) = $epipe->drain_func
606
607These two methods returns a function pointer and C<void *> argument
608that can be called to have the effect of C<< $epipe->signal >> or C<<
609$epipe->drain >>, respectively, on the XS level.
610
611They both have the following prototype and need to be passed their
612C<$c_arg>, which is a C<void *> cast to an C<IV>:
613
614 void (*c_func) (void *c_arg)
615
616An example call would look like:
617
618 c_func (c_arg);
619
620=item $epipe->post_fork
621
622Recreates the pipe (usually required in the child after a fork). The
623reading side will not change it's file descriptor number, but the writing
624side might.
625
626=item $epipe->wait
627
628This method blocks the process until there are events on the pipe. This is
629not a very event-based or ncie way of usign an event pipe, but it can be
630occasionally useful.
631
632=back
269 633
270=cut 634=cut
271 635
2721; 6361;
273
274=back
275
276=head1 EXAMPLE
277
278There really should be a complete C/XS example. Bug me about it. Better
279yet, create one.
280 637
281=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 638=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
282 639
283This module works by "hijacking" SIGKILL, which is guaranteed to always 640This module works by "hijacking" SIGKILL, which is guaranteed to always
284exist, but also cannot be caught, so is always available. 641exist, but also cannot be caught, so is always available.
287then intercepts the interpreter handling it. This makes normal signal 644then intercepts the interpreter handling it. This makes normal signal
288handling slower (probably unmeasurably, though), but has the advantage 645handling slower (probably unmeasurably, though), but has the advantage
289of not requiring a special runops function, nor slowing down normal perl 646of not requiring a special runops function, nor slowing down normal perl
290execution a bit. 647execution a bit.
291 648
292It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify 649It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
293(C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we 650modify.
294can assume that this is quite portable, at least w.r.t. signals).
295 651
296=head1 AUTHOR 652=head1 AUTHOR
297 653
298 Marc Lehmann <schmorp@schmorp.de> 654 Marc Lehmann <schmorp@schmorp.de>
299 http://home.schmorp.de/ 655 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines