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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.15 by root, Fri Jul 17 14:59:47 2009 UTC vs.
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC

 For example the deliantra game server uses a variant of this technique
 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
 One could use this module e.g. in L<Coro> to interrupt a running coro-thread
 I<running> interpreter, there is optional support for signalling a 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.
+=head1 THE Async::Interrupt CLASS
 =over 4
 =cut
 package Async::Interrupt;
 BEGIN {
    # the next line forces initialisation of internal
    # signal handling # variables
    $SIG{KILL} = sub { };
-   our $VERSION = '0.501';
+   our $VERSION = '0.6';
    require XSLoader;
    XSLoader::load ("Async::Interrupt", $VERSION);
 }
 which case the requirements set out for C<cb> apply as well).
 =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.
 Note that the only thing you are legally allowed to do is to is to check
 the variable in a boolean or integer context (e.g. comparing it with a
 This can be used to ensure that async notifications will interrupt event
 frameworks as well.
 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.
 =back
 =cut
    bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
 }
 =item ($signal_func, $signal_arg) = $async->signal_func
-Returns the address of a function to call asynchronously. The function has
+Returns the address of a function to call asynchronously. The function
-the following prototype and needs to be passed the specified C<$c_arg>,
+has the following prototype and needs to be passed the specified
-which is a C<void *> cast to C<IV>:
+C<$signal_arg>, which is a C<void *> cast to C<IV>:
    void (*signal_func) (void *signal_arg, int value)
 An example call would look like:
            CODE:
            valuep = (IV *)addr;
    // 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
 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 ($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
 Note that the only valid oepration 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)
+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
 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
 This only works when the pipe was created by Async::Interrupt.
 Async::Interrupt ensures that the reading file descriptor does not change
 it's value.
+=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 $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.
+=back
 =cut
 1;
-=back
 =head1 EXAMPLE
 There really should be a complete C/XS example. Bug me about it. Better
 yet, create one.

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.15 by root, Fri Jul 17 14:59:47 2009 UTC vs. Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.15 by root, Fri Jul 17 14:59:47 2009 UTC vs.
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC