[ViewVC] Diff of: cvs/cvsroot/Async-Interrupt/Interrupt.pm

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.27 by root, Sat May 15 00:08:48 2010 UTC vs.
Revision 1.40 by root, Mon Apr 27 11:34:31 2020 UTC

 You can use this module to bind a signal to a callback while at the same
 time activating an event pipe that you can C<select> on, fixing the race
 completely.
-This can be used to implement the signal hadling in event loops,
+This can be used to implement the signal handling in event loops,
 e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
 =item Background threads want speedy reporting
 Assume you want very exact timing, and you can spare an extra cpu core
 callback just sets a global variable, as we are only interested in
 synchronous signals (i.e. when the event loop polls), which is why the
 pipe draining is not done automatically.
    my $interrupt = new Async::Interrupt
-      cb             => sub { undef $SIGNAL_RECEIVED{$signum} }
+      cb             => sub { undef $SIGNAL_RECEIVED{$signum} },
       signal         => $signum,
       pipe           => [$SIGPIPE->filenos],
       pipe_autodrain => 0,
    ;
    _attach $self, $asy->signal_func;
 So to repeat: first the XS object is created, then it is queried for the
 callback that should be called when the Interrupt object gets signalled.
-Then the interrupt object is queried for the callback fucntion that the
+Then the interrupt object is queried for the callback function that the
 thread should call to signal the Interrupt object, and this callback is
 then attached to the thread.
 You have to be careful that your new thread is not signalling before the
 signal function was configured, for example by starting the background
    # the next line forces initialisation of internal
    # signal handling variables, otherwise, PL_sig_pending
    # etc. might be null pointers.
    $SIG{KILL} = sub { };
-   our $VERSION = '1.05';
+   our $VERSION = 1.26;
    require XSLoader;
    XSLoader::load ("Async::Interrupt", $VERSION);
 }
 might imply, do anything with POSIX signals).
 C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
 (1..127 is portable).
+=item $async->handle
+Calls the callback if the object is pending.
+This method does not need to be called normally, as it will be invoked
+automatically. However, it can be used to force handling of outstanding
+interrupts while the object is blocked.
+One reason why one might want to do that is when you want to switch
+from asynchronous interruptions to synchronous one, using e.g. an event
+loop. To do that, one would first C<< $async->block >> the interrupt
+object, then register a read watcher on the C<pipe_fileno> that calls C<<
+$async->handle >>.
+This disables asynchronous interruptions, but ensures that interrupts are
+handled by the event loop.
 =item $async->signal_hysteresis ($enable)
 Enables or disables signal hysteresis (default: disabled). If a POSIX
 signal is used as a signal source for the interrupt object, then enabling
 signal hysteresis causes Async::Interrupt to reset the signal action to
 When you expect a lot of signals (e.g. when using SIGIO), then enabling
 signal hysteresis can reduce the number of handler invocations
 considerably, at the cost of two extra syscalls.
 Note that setting the signal to C<SIG_IGN> can have unintended side
-effects when you fork and exec other programs, as often they do nto expect
+effects when you fork and exec other programs, as often they do not expect
 signals to be ignored by default.
 =item $async->block
 =item $async->unblock
 =item $fileno = $async->pipe_fileno
 Returns the reading side of the signalling pipe. If no signalling pipe is
 currently attached to the object, it will dynamically create one.
-Note that the only valid oepration on this file descriptor is to wait
+Note that the only valid operation on this file descriptor is to wait
 until it is readable. The fd might belong currently to a pipe, a tcp
 socket, or an eventfd, depending on the platform, and is guaranteed to be
 C<select>able.
 =item $async->pipe_autodrain ($enable)
 draining.
 This is useful when you want to share one pipe among many Async::Interrupt
 objects.
+=item $async->pipe_drain
+Drains the pipe manually, for example, when autodrain is disabled. Does
+nothing when no pipe is enabled.
 =item $async->post_fork
 The object will not normally be usable after a fork (as the pipe fd is
 shared between processes). Calling this method after a fork in the child
 ensures that the object will work as expected again. It only needs to be
    c_func (c_arg);
 =item $epipe->renew
-Recreates the pipe (useful after a fork). The reading side will not change
+Recreates the pipe (usually required in the child after a fork). The
-it's file descriptor number, but the writing side might.
+reading side will not change it's file descriptor number, but the writing
+side might.
 =item $epipe->wait
 This method blocks the process until there are events on the pipe. This is
 not a very event-based or ncie way of usign an event pipe, but it can be
 =head1 IMPLEMENTATION DETAILS AND LIMITATIONS
 This module works by "hijacking" SIGKILL, which is guaranteed to always
 exist, but also cannot be caught, so is always available.
-Basically, this module fakes the occurance of a SIGKILL signal and
+Basically, this module fakes the occurence of a SIGKILL signal and
 then intercepts the interpreter handling it. This makes normal signal
 handling slower (probably unmeasurably, though), but has the advantage
 of not requiring a special runops function, nor slowing down normal perl
 execution a bit.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.27 by root, Sat May 15 00:08:48 2010 UTC vs. Revision 1.40 by root, Mon Apr 27 11:34:31 2020 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.27 by root, Sat May 15 00:08:48 2010 UTC vs.
Revision 1.40 by root, Mon Apr 27 11:34:31 2020 UTC