--- Async-Interrupt/Interrupt.pm	2009/07/17 01:53:41	1.14
+++ Async-Interrupt/Interrupt.pm	2009/07/30 03:59:47	1.21
@@ -55,6 +55,9 @@
 to interrupt background processes regularly to send map updates to game
 clients.
 
+Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
+events have arrived.
+
 L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
 
 =item Speedy event loop invocation
@@ -90,6 +93,137 @@
 L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
 and C<write> syscall.
 
+=head1 USAGE EXAMPLES
+
+=head2 Implementing race-free signal handling
+
+This example uses a single event pipe for all signals, and one
+Async::Interrupt per signal. This code is actually what the L<AnyEvent>
+module uses itself when Async::Interrupt is available.
+
+First, create the event pipe and hook it into the event loop
+
+   $SIGPIPE = new Async::Interrupt::EventPipe;
+   $SIGPIPE_W = AnyEvent->io (
+      fh   => $SIGPIPE->fileno,
+      poll => "r",
+      cb   => \&_signal_check, # defined later
+   );
+
+Then, for each signal to hook, create an Async::Interrupt object. The
+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} }
+      signal         => $signum,
+      pipe           => [$SIGPIPE->filenos],
+      pipe_autodrain => 0,
+   ;
+
+Finally, the I/O callback for the event pipe handles the signals:
+
+   sub _signal_check {
+      # drain the pipe first
+      $SIGPIPE->drain;
+
+      # two loops, just to be sure
+      while (%SIGNAL_RECEIVED) {
+         for (keys %SIGNAL_RECEIVED) {
+            delete $SIGNAL_RECEIVED{$_};
+            warn "signal $_ received\n";
+         }
+      }
+   }
+
+=head2 Interrupt perl from another thread
+
+This example interrupts the Perl interpreter from another thread, via the
+XS API. This is used by e.g. the L<EV::Loop::Async> module.
+
+On the Perl level, a new loop object (which contains the thread)
+is created, by first calling some XS constructor, querying the
+C-level callback function and feeding that as the C<c_cb> into the
+Async::Interrupt constructor:
+
+   my $self = XS_thread_constructor;
+   my ($c_func, $c_arg) = _c_func $self; # return the c callback
+   my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg];
+
+Then the newly created Interrupt object is queried for the signaling
+function that the newly created thread should call, and this is in turn
+told to the thread object:
+
+   _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
+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
+thread only within C<_attach>.
+
+That concludes the Perl part.
+
+The XS part consists of the actual constructor which creates a thread,
+which is not relevant for this example, and two functions, C<_c_func>,
+which returns the Perl-side callback, and C<_attach>, which configures
+the signalling functioon that is safe toc all from another thread. For
+simplicity, we will use global variables to store the functions, normally
+you would somehow attach them to C<$self>.
+
+The C<c_func> simply returns the address of a static function and arranges
+for the object pointed to by C<$self> to be passed to it, as an integer:
+
+   void
+   _c_func (SV *loop)
+           PPCODE:
+           EXTEND (SP, 2);
+           PUSHs (sv_2mortal (newSViv (PTR2IV (c_func))));
+           PUSHs (sv_2mortal (newSViv (SvRV (loop))));
+
+This would be the callback (since it runs in a normal Perl context, it is
+permissible to manipulate Perl values):
+
+   static void
+   c_func (pTHX_ void *loop_, int value)
+   {
+     SV *loop_object = (SV *)loop_;
+     ...
+   }
+
+And this attaches the signalling callback:
+
+   static void (*my_sig_func) (void *signal_arg, int value);
+   static void *my_sig_arg;
+
+   void
+   _attach (SV *loop_, IV sig_func, void *sig_arg)
+           CODE:
+   {
+           my_sig_func = sig_func;
+           my_sig_arg  = sig_arg;
+
+           /* now run the thread */
+           thread_create (&u->tid, l_run, 0);
+   }
+
+And C<l_run> (the background thread) would eventually call the signaling
+function:
+
+   my_sig_func (my_sig_arg, 0);
+
+You can have a look at L<EV::Loop::Async> for an actual example using
+intra-thread communication, locking and so on.
+
+
+=head1 THE Async::Interrupt CLASS
+
 =over 4
 
 =cut
@@ -100,10 +234,11 @@
 
 BEGIN {
    # the next line forces initialisation of internal
-   # signal handling # variables
+   # signal handling variables, otherwise, PL_sig_pending
+   # etc. will be null pointers.
    $SIG{KILL} = sub { };
 
-   our $VERSION = '0.5';
+   our $VERSION = '1.0';
 
    require XSLoader;
    XSLoader::load ("Async::Interrupt", $VERSION);
@@ -136,7 +271,7 @@
 
 If the callback should throw an exception, then it will be caught,
 and C<$Async::Interrupt::DIED> will be called with C<$@> containing
-the exception.  The default will simply C<warn> about the message and
+the exception. The default will simply C<warn> about the message and
 continue.
 
 =item c_cb => [$c_func, $c_arg]
@@ -162,7 +297,7 @@
 =item var => $scalar_ref
 
 When specified, then the given argument must be a reference to a
-scalar. The scalar will be set to C<0> intiially. Signalling the interrupt
+scalar. The scalar will be set to C<0> initially. Signalling the interrupt
 object will set it to the passed value, handling the interrupt will reset
 it to C<0> again.
 
@@ -180,6 +315,11 @@
 Only one async can hook a given signal, and the signal will be restored to
 defaults when the Async::Interrupt object gets destroyed.
 
+=item signal_hysteresis => $boolean
+
+Sets the initial signal hysteresis state, see the C<signal_hysteresis>
+method, below.
+
 =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
 
 Specifies two file descriptors (or file handles) that should be signalled
@@ -196,7 +336,15 @@
 
 Note that C<Async::Interrupt> will create a suitable signal fd
 automatically when your program requests one, so you don't have to specify
-this agrument when all you want is an extra file descriptor to watch.
+this argument when all you want is an extra file descriptor to watch.
+
+If you want to share a single event pipe between multiple Async::Interrupt
+objects, you can use the C<Async::Interrupt::EventPipe> class to manage
+those.
+
+=item pipe_autodrain => $boolean
+
+Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
 
 =back
 
@@ -205,14 +353,21 @@
 sub new {
    my ($class, %arg) = @_;
 
-   bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
+   my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
+
+   # urgs, reminds me of Event
+   for my $attr (qw(pipe_autodrain signal_hysteresis)) {
+      $self->$attr ($arg{$attr}) if exists $arg{$attr};
+   }
+
+   $self
 }
 
 =item ($signal_func, $signal_arg) = $async->signal_func
 
-Returns the address of a function to call asynchronously. The function has
-the following prototype and needs to be passed the specified C<$c_arg>,
-which is a C<void *> cast to C<IV>:
+Returns the address of a function to call asynchronously. The function
+has the following prototype and needs to be passed the specified
+C<$signal_arg>, which is a C<void *> cast to C<IV>:
 
    void (*signal_func) (void *signal_arg, int value)
 
@@ -255,16 +410,33 @@
 
    // code in a loop, waiting
    while (!*valuep)
-     ; // do soemthing
+     ; // do something
 
 =item $async->signal ($value=1)
 
 This signals the given async object from Perl code. Semi-obviously, this
-will instantly trigger the callback invocation.
+will instantly trigger the callback invocation (it does not, as the name
+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->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
+C<SIG_IGN> in the signal handler and restore it just before handling the
+interruption.
+
+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
+signals to be ignored by default.
+
 =item $async->block
 
 =item $async->unblock
@@ -289,6 +461,23 @@
 
 This is the recommended (and fastest) way to implement critical sections.
 
+=item ($block_func, $block_arg) = $async->scope_block_func
+
+Returns the address of a function that implements the C<scope_block>
+functionality.
+
+It has the following prototype and needs to be passed the specified
+C<$block_arg>, which is a C<void *> cast to C<IV>:
+
+   void (*block_func) (void *block_arg)
+
+An example call would look like:
+
+   block_func (block_arg);
+
+The function is safe to call only from within the toplevel of a perl XS
+function and will call C<LEAVE> and C<ENTER> (in this order!).
+
 =item $async->pipe_enable
 
 =item $async->pipe_disable
@@ -313,6 +502,16 @@
 socket, or an eventfd, depending on the platform, and is guaranteed to be
 C<select>able.
 
+=item $async->pipe_autodrain ($enable)
+
+Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
+enabled). When automatic draining is enabled, then Async::Interrupt will
+automatically clear the pipe. Otherwise the user is responsible for this
+draining.
+
+This is useful when you want to share one pipe among many Async::Interrupt
+objects.
+
 =item $async->post_fork
 
 The object will not normally be usable after a fork (as the pipe fd is
@@ -325,16 +524,90 @@
 Async::Interrupt ensures that the reading file descriptor does not change
 it's value.
 
-=cut
+=item $signum = Async::Interrupt::sig2num $signame_or_number
 
-1;
+=item $signame = Async::Interrupt::sig2name $signame_or_number
+
+These two convenience functions simply convert a signal name or number to
+the corresponding name or number. They are not used by this module and
+exist just because perl doesn't have a nice way to do this on its own.
+
+They will return C<undef> on illegal names or numbers.
+
+=back
+
+=head1 THE Async::Interrupt::EventPipe CLASS
+
+Pipes are the predominent 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
+windows, it will try to create a tcp socket pair, on GNU/Linux, it will
+try to create an eventfd and everywhere else it will try to use a normal
+pipe.
+
+=over 4
+
+=item $epipe = new Async::Interrupt::EventPipe
+
+This creates and returns an eventpipe object. This object is simply a
+blessed array reference:
+
+=item ($r_fd, $w_fd) = $epipe->filenos
+
+Returns the read-side file descriptor and the write-side file descriptor.
+
+Example: pass an eventpipe object as pipe to the Async::Interrupt
+constructor, and create an AnyEvent watcher for the read side.
+
+   my $epipe = new Async::Interrupt::EventPipe;
+   my $asy = new Async::Interrupt pipe => [$epipe->filenos];
+   my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
+
+=item $r_fd = $epipe->fileno
+
+Return only the reading/listening side.
+
+=item $epipe->signal
+
+Write something to the pipe, in a portable fashion.
+
+=item $epipe->drain
+
+Drain (empty) the pipe.
+
+=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.
+
+It has the following prototype and needs to be passed the specified
+C<$c_arg>, which is a C<void *> cast to 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
+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
+occasionally useful.
 
 =back
 
-=head1 EXAMPLE
+=cut
 
-There really should be a complete C/XS example. Bug me about it. Better
-yet, create one.
+1;
 
 =head1 IMPLEMENTATION DETAILS AND LIMITATIONS