--- Async-Interrupt/Interrupt.pm	2009/07/02 15:13:03	1.2
+++ Async-Interrupt/Interrupt.pm	2009/07/02 16:15:52	1.4
@@ -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
 
@@ -101,10 +103,10 @@
 
 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 pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
 
@@ -116,7 +118,7 @@
 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).
+e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution).
 
 The object will keep a reference to the file handles.
 
@@ -167,10 +169,28 @@
 
 =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.
+
 =cut
 
 1;
@@ -179,11 +199,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 +213,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