… | |
… | |
114 | callback just sets a global variable, as we are only interested in |
114 | callback just sets a global variable, as we are only interested in |
115 | synchronous signals (i.e. when the event loop polls), which is why the |
115 | synchronous signals (i.e. when the event loop polls), which is why the |
116 | pipe draining is not done automatically. |
116 | pipe draining is not done automatically. |
117 | |
117 | |
118 | my $interrupt = new Async::Interrupt |
118 | my $interrupt = new Async::Interrupt |
119 | cb => sub { undef $SIGNAL_RECEIVED{$signum} } |
119 | cb => sub { undef $SIGNAL_RECEIVED{$signum} }, |
120 | signal => $signum, |
120 | signal => $signum, |
121 | pipe => [$SIGPIPE->filenos], |
121 | pipe => [$SIGPIPE->filenos], |
122 | pipe_autodrain => 0, |
122 | pipe_autodrain => 0, |
123 | ; |
123 | ; |
124 | |
124 | |
… | |
… | |
233 | use common::sense; |
233 | use common::sense; |
234 | |
234 | |
235 | BEGIN { |
235 | BEGIN { |
236 | # the next line forces initialisation of internal |
236 | # the next line forces initialisation of internal |
237 | # signal handling variables, otherwise, PL_sig_pending |
237 | # signal handling variables, otherwise, PL_sig_pending |
238 | # etc. will be null pointers. |
238 | # etc. might be null pointers. |
239 | $SIG{KILL} = sub { }; |
239 | $SIG{KILL} = sub { }; |
240 | |
240 | |
241 | our $VERSION = '1.02'; |
241 | our $VERSION = '1.2'; |
242 | |
242 | |
243 | require XSLoader; |
243 | require XSLoader; |
244 | XSLoader::load ("Async::Interrupt", $VERSION); |
244 | XSLoader::load ("Async::Interrupt", $VERSION); |
245 | } |
245 | } |
246 | |
246 | |
… | |
… | |
419 | might imply, do anything with POSIX signals). |
419 | might imply, do anything with POSIX signals). |
420 | |
420 | |
421 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
421 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
422 | (1..127 is portable). |
422 | (1..127 is portable). |
423 | |
423 | |
|
|
424 | =item $async->handle |
|
|
425 | |
|
|
426 | Calls the callback if the object is pending. |
|
|
427 | |
|
|
428 | This method does not need to be called normally, as it will be invoked |
|
|
429 | automatically. However, it can be used to force handling of outstanding |
|
|
430 | interrupts while the object is blocked. |
|
|
431 | |
|
|
432 | One reason why one might want to do that is when you want to switch |
|
|
433 | from asynchronous interruptions to synchronous one, using e.g. an event |
|
|
434 | loop. To do that, one would first C<< $async->block >> the interrupt |
|
|
435 | object, then register a read watcher on the C<pipe_fileno> that calls C<< |
|
|
436 | $async->handle >>. |
|
|
437 | |
|
|
438 | This disables asynchronous interruptions, but ensures that interrupts are |
|
|
439 | handled by the event loop. |
|
|
440 | |
424 | =item $async->signal_hysteresis ($enable) |
441 | =item $async->signal_hysteresis ($enable) |
425 | |
442 | |
426 | Enables or disables signal hysteresis (default: disabled). If a POSIX |
443 | Enables or disables signal hysteresis (default: disabled). If a POSIX |
427 | signal is used as a signal source for the interrupt object, then enabling |
444 | signal is used as a signal source for the interrupt object, then enabling |
428 | signal hysteresis causes Async::Interrupt to reset the signal action to |
445 | signal hysteresis causes Async::Interrupt to reset the signal action to |
… | |
… | |
432 | When you expect a lot of signals (e.g. when using SIGIO), then enabling |
449 | When you expect a lot of signals (e.g. when using SIGIO), then enabling |
433 | signal hysteresis can reduce the number of handler invocations |
450 | signal hysteresis can reduce the number of handler invocations |
434 | considerably, at the cost of two extra syscalls. |
451 | considerably, at the cost of two extra syscalls. |
435 | |
452 | |
436 | Note that setting the signal to C<SIG_IGN> can have unintended side |
453 | Note that setting the signal to C<SIG_IGN> can have unintended side |
437 | effects when you fork and exec other programs, as often they do nto expect |
454 | effects when you fork and exec other programs, as often they do not expect |
438 | signals to be ignored by default. |
455 | signals to be ignored by default. |
439 | |
456 | |
440 | =item $async->block |
457 | =item $async->block |
441 | |
458 | |
442 | =item $async->unblock |
459 | =item $async->unblock |
… | |
… | |
495 | =item $fileno = $async->pipe_fileno |
512 | =item $fileno = $async->pipe_fileno |
496 | |
513 | |
497 | Returns the reading side of the signalling pipe. If no signalling pipe is |
514 | Returns the reading side of the signalling pipe. If no signalling pipe is |
498 | currently attached to the object, it will dynamically create one. |
515 | currently attached to the object, it will dynamically create one. |
499 | |
516 | |
500 | Note that the only valid oepration on this file descriptor is to wait |
517 | Note that the only valid operation on this file descriptor is to wait |
501 | until it is readable. The fd might belong currently to a pipe, a tcp |
518 | until it is readable. The fd might belong currently to a pipe, a tcp |
502 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
519 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
503 | C<select>able. |
520 | C<select>able. |
504 | |
521 | |
505 | =item $async->pipe_autodrain ($enable) |
522 | =item $async->pipe_autodrain ($enable) |
… | |
… | |
510 | draining. |
527 | draining. |
511 | |
528 | |
512 | This is useful when you want to share one pipe among many Async::Interrupt |
529 | This is useful when you want to share one pipe among many Async::Interrupt |
513 | objects. |
530 | objects. |
514 | |
531 | |
|
|
532 | =item $async->pipe_drain |
|
|
533 | |
|
|
534 | Drains the pipe manually, for example, when autodrain is disabled. Does |
|
|
535 | nothing when no pipe is enabled. |
|
|
536 | |
515 | =item $async->post_fork |
537 | =item $async->post_fork |
516 | |
538 | |
517 | The object will not normally be usable after a fork (as the pipe fd is |
539 | The object will not normally be usable after a fork (as the pipe fd is |
518 | shared between processes). Calling this method after a fork in the child |
540 | shared between processes). Calling this method after a fork in the child |
519 | ensures that the object will work as expected again. It only needs to be |
541 | ensures that the object will work as expected again. It only needs to be |
… | |
… | |
536 | |
558 | |
537 | =back |
559 | =back |
538 | |
560 | |
539 | =head1 THE Async::Interrupt::EventPipe CLASS |
561 | =head1 THE Async::Interrupt::EventPipe CLASS |
540 | |
562 | |
541 | Pipes are the predominent utility to make asynchronous signals |
563 | Pipes are the predominant utility to make asynchronous signals |
542 | synchronous. However, pipes are hard to come by: they don't exist on the |
564 | synchronous. However, pipes are hard to come by: they don't exist on the |
543 | broken windows platform, and on GNU/Linux systems, you might want to use |
565 | broken windows platform, and on GNU/Linux systems, you might want to use |
544 | an C<eventfd> instead. |
566 | an C<eventfd> instead. |
545 | |
567 | |
546 | This class creates selectable event pipes in a portable fashion: on |
568 | This class creates selectable event pipes in a portable fashion: on |
… | |
… | |
576 | |
598 | |
577 | =item $epipe->drain |
599 | =item $epipe->drain |
578 | |
600 | |
579 | Drain (empty) the pipe. |
601 | Drain (empty) the pipe. |
580 | |
602 | |
|
|
603 | =item ($c_func, $c_arg) = $epipe->signal_func |
|
|
604 | |
581 | =item ($c_func, $c_arg) = $epipe->drain_func |
605 | =item ($c_func, $c_arg) = $epipe->drain_func |
582 | |
606 | |
583 | Returns a function pointer and C<void *> argument that can be called to |
607 | These two methods returns a function pointer and C<void *> argument |
584 | have the effect of C<< $epipe->drain >> on the XS level. |
608 | that can be called to have the effect of C<< $epipe->signal >> or C<< |
|
|
609 | $epipe->drain >>, respectively, on the XS level. |
585 | |
610 | |
586 | It has the following prototype and needs to be passed the specified |
611 | They both have the following prototype and need to be passed their |
587 | C<$c_arg>, which is a C<void *> cast to C<IV>: |
612 | C<$c_arg>, which is a C<void *> cast to an C<IV>: |
588 | |
613 | |
589 | void (*c_func) (void *c_arg) |
614 | void (*c_func) (void *c_arg) |
590 | |
615 | |
591 | An example call would look like: |
616 | An example call would look like: |
592 | |
617 | |