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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC vs.
Revision 1.38 by root, Sun Apr 21 09:42:27 2019 UTC

 L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
 and C<write> syscall.
 =head1 USAGE EXAMPLES
-=head2 Async::Interrupt to implement race-free signal handling
+=head2 Implementing race-free signal handling
 This example uses a single event pipe for all signals, and one
-Async::Interrupt per signal.
+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 (this code is
+First, create the event pipe and hook it into the event loop
-actually what L<AnyEvent> uses itself):
    $SIGPIPE = new Async::Interrupt::EventPipe;
    $SIGPIPE_W = AnyEvent->io (
       fh   => $SIGPIPE->fileno,
       poll => "r",
-      cb   => \&_signal_check,
+      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} }
+      cb             => sub { undef $SIGNAL_RECEIVED{$signum} },
-      signal         => $signal,
+      signal         => $signum,
-      pipe           => [$SIGPIPE_R->filenos],
+      pipe           => [$SIGPIPE->filenos],
       pipe_autodrain => 0,
    ;
 Finally, the I/O callback for the event pipe handles the signals:
             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
 use common::sense;
 BEGIN {
    # the next line forces initialisation of internal
-   # signal handling # variables
+   # signal handling variables, otherwise, PL_sig_pending
+   # etc. might be null pointers.
    $SIG{KILL} = sub { };
-   our $VERSION = '0.6';
+   our $VERSION = 1.25;
    require XSLoader;
    XSLoader::load ("Async::Interrupt", $VERSION);
 }
 The exceptions are C<$!> and C<$@>, which are saved and restored by
 Async::Interrupt.
 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]
 Registers a C callback the be invoked whenever the async interrupt is
 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 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
 whenever the async interrupt is signalled. This means a single octet will
 be written to it, and before the callback is being invoked, it will be
 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
 =cut
 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
 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
+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.
+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)
+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
+occasionally useful.
 =back
 =cut
 1;
-=head1 EXAMPLE
-There really should be a complete C/XS example. Bug me about it. Better
-yet, create one.
 =head1 IMPLEMENTATION DETAILS AND LIMITATIONS
 This module works by "hijacking" SIGKILL, which is guaranteed to always
 exist, but also cannot be caught, so is always available.

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC vs. Revision 1.38 by root, Sun Apr 21 09:42:27 2019 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC vs.
Revision 1.38 by root, Sun Apr 21 09:42:27 2019 UTC