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

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.21 by root, Thu Jul 30 03:59:47 2009 UTC vs.
Revision 1.37 by root, Tue Apr 17 19:24:32 2018 UTC

 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,
    ;
 use common::sense;
 BEGIN {
    # the next line forces initialisation of internal
    # signal handling variables, otherwise, PL_sig_pending
-   # etc. will be null pointers.
+   # etc. might be null pointers.
    $SIG{KILL} = sub { };
-   our $VERSION = '1.0';
+   our $VERSION = 1.24;
    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
 =back
 =head1 THE Async::Interrupt::EventPipe CLASS
-Pipes are the predominent utility to make asynchronous signals
+Pipes are the predominant utility to make asynchronous signals
 synchronous. However, pipes are hard to come by: they don't exist on the
 broken windows platform, and on GNU/Linux systems, you might want to use
 an C<eventfd> instead.
 This class creates selectable event pipes in a portable fashion: on
 =item $epipe->drain
 Drain (empty) the pipe.
+=item ($c_func, $c_arg) = $epipe->signal_func
 =item ($c_func, $c_arg) = $epipe->drain_func
-Returns a function pointer and C<void *> argument that can be called to
+These two methods returns a function pointer and C<void *> argument
-have the effect of C<< $epipe->drain >> on the XS level.
+that can be called to have the effect of C<< $epipe->signal >> or C<<
+$epipe->drain >>, respectively, on the XS level.
-It has the following prototype and needs to be passed the specified
+They both have the following prototype and need to be passed their
-C<$c_arg>, which is a C<void *> cast to C<IV>:
+C<$c_arg>, which is a C<void *> cast to an C<IV>:
    void (*c_func) (void *c_arg)
 An example call would look like:
    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

Diff Legend

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

Comparing Async-Interrupt/Interrupt.pm (file contents): Revision 1.21 by root, Thu Jul 30 03:59:47 2009 UTC vs. Revision 1.37 by root, Tue Apr 17 19:24:32 2018 UTC

Diff Legend

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.21 by root, Thu Jul 30 03:59:47 2009 UTC vs.
Revision 1.37 by root, Tue Apr 17 19:24:32 2018 UTC