--- Async-Interrupt/Interrupt.pm	2009/07/02 15:13:03	1.2
+++ Async-Interrupt/Interrupt.pm	2009/07/11 22:24:30	1.7
@@ -9,7 +9,7 @@
 =head1 DESCRIPTION
 
 This module implements a single feature only of interest to advanced perl
-modules, namely asynchronous interruptions (think "unix signals", which
+modules, namely asynchronous interruptions (think "UNIX signals", which
 are very similar).
 
 Sometimes, modules wish to run code asynchronously (in another thread),
@@ -39,7 +39,9 @@
 
 Since this kind of interruption is fast, but can only interrupt a
 I<running> interpreter, there is optional support for also signalling a
-pipe - that means you can also wait for the pipe to become readable while
+pipe - that means you can also wait for the pipe to become readable (e.g.
+via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a
+C<read> and C<write> syscall.
 
 =over 4
 
@@ -50,7 +52,7 @@
 no warnings;
 
 BEGIN {
-   $VERSION = '0.02';
+   $VERSION = '0.04';
 
    require XSLoader;
    XSLoader::load Async::Interrupt::, $VERSION;
@@ -101,10 +103,19 @@
 
 Note that, because the callback can be invoked at almost any time, you
 have to be careful at saving and restoring global variables that Perl
-might use (the excetpion is C<errno>, which is aved and restored by
+might use (the exception is C<errno>, which is saved and restored by
 Async::Interrupt). The callback itself runs as part of the perl context,
 so you can call any perl functions and modify any perl data structures (in
-which case the requireemnts set out for C<cb> apply as well).
+which case the requirements set out for C<cb> apply as well).
+
+=item signal => $signame_or_value
+
+When this parameter is specified, then the Async::Interrupt will hook the
+given signal, that is, it will effectively call C<< ->signal (0) >> each time
+the given signal is caught by the process.
+
+Only one async can hook a given signal, and the signal will be restored to
+defaults when the Async::Interrupt object gets destroyed.
 
 =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
 
@@ -115,8 +126,11 @@
 are written. It is required that the file handles are both in nonblocking
 mode.
 
-(You can get a portable pipe and set non-blocking mode portably by using
-e.g. L<AnyEvent::Util> from the L<AnyEvent> distro).
+You can get a portable pipe and set non-blocking mode portably by using
+e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
+
+It is also possible to pass in a linux eventfd as both read and write
+handle (which is faster than a pipe).
 
 The object will keep a reference to the file handles.
 
@@ -130,7 +144,7 @@
 sub new {
    my ($class, %arg) = @_;
 
-   bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class
+   bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class
 }
 
 =item ($signal_func, $signal_arg) = $async->signal_func
@@ -167,10 +181,41 @@
 
 =item $async->block
 
-Sometimes you need a "critical section" of code where
-
 =item $async->unblock
 
+Sometimes you need a "critical section" of code that will not be
+interrupted by an Async::Interrupt. This can be implemented by calling C<<
+$async->block >> before the critical section, and C<< $async->unblock >>
+afterwards.
+
+Note that there must be exactly one call of C<unblock> for every previous
+call to C<block> (i.e. calls can nest).
+
+Since ensuring this in the presence of exceptions and threads is
+usually more difficult than you imagine, I recommend using C<<
+$async->scoped_block >> instead.
+
+=item $async->scope_block
+
+This call C<< $async->block >> and installs a handler that is called when
+the current scope is exited (via an exception, by canceling the Coro
+thread, by calling last/goto etc.).
+
+This is the recommended (and fastest) way to implement critical sections.
+
+=item $async->pipe_enable
+
+=item $async->pipe_disable
+
+Enable/disable signalling the pipe when the interrupt occurs (default is
+enabled). Writing to a pipe is relatively expensive, so it can be disabled
+when you know you are not waiting for it (for example, with L<EV> you
+could disable the pipe in a check watcher, and enable it in a prepare
+watcher).
+
+Note that when C<fd_disable> is in effect, no attempt to read from the
+pipe will be done.
+
 =cut
 
 1;
@@ -179,11 +224,11 @@
 
 =head1 EXAMPLE
 
-#TODO
+There really should be a complete C/XS example. Bug me about it.
 
 =head1 IMPLEMENTATION DETAILS AND LIMITATIONS
 
-This module works by "hijacking" SIGKILL, which is guarenteed to be always
+This module works by "hijacking" SIGKILL, which is guaranteed to be always
 available in perl, but also cannot be caught, so is always available.
 
 Basically, this module fakes the receive of a SIGKILL signal and
@@ -193,7 +238,7 @@
 
 It assumes that C<sig_atomic_t> and C<int> are both exception-safe to
 modify (C<sig_atomic_> is used by this module, and perl itself uses
-C<int>, so we can assume that this is quite portbale, at least w.r.t.
+C<int>, so we can assume that this is quite portable, at least w.r.t.
 signals).
 
 =head1 AUTHOR