--- Async-Interrupt/Interrupt.pm	2009/07/30 03:59:47	1.21
+++ Async-Interrupt/Interrupt.pm	2015/02/11 19:31:21	1.34
@@ -116,7 +116,7 @@
 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,
@@ -235,10 +235,10 @@
 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.21;
 
    require XSLoader;
    XSLoader::load ("Async::Interrupt", $VERSION);
@@ -421,6 +421,23 @@
 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
@@ -434,7 +451,7 @@
 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
@@ -497,7 +514,7 @@
 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.
@@ -512,6 +529,11 @@
 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
@@ -538,7 +560,7 @@
 
 =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.
@@ -578,13 +600,16 @@
 
 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
-have the effect of C<< $epipe->drain >> on the XS level.
+These two methods returns a function pointer and C<void *> argument
+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
-C<$c_arg>, which is a C<void *> cast to C<IV>:
+They both have the following prototype and need to be passed their
+C<$c_arg>, which is a C<void *> cast to an C<IV>:
 
    void (*c_func) (void *c_arg)