view release on metacpan or  search on metacpan

Interrupt.pm  view on Meta::CPAN

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:

   signal_func (signal_arg, 0);

The function is safe to call from within signal and thread contexts, at
any time. The specified C<value> is passed to both C and Perl callback.

C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
(1..127 is portable).

If the function is called while the Async::Interrupt object is already
signaled but before the callbacks are being executed, then the stored
C<value> is either the old or the new one. Due to the asynchronous
nature of the code, the C<value> can even be passed to two consecutive
invocations of the callback.

=item $address = $async->c_var

Returns the address (cast to IV) of an C<IV> variable. The variable is set
to C<0> initially and gets set to the passed value whenever the object
gets signalled, and reset to C<0> once the interrupt has been handled.

Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
handle any interrupts.

Example: call some XS function to store the address, then show C code
waiting for it.

   my_xs_func $async->c_var;

   static IV *valuep;

   void
   my_xs_func (void *addr)
           CODE:
           valuep = (IV *)addr;

   // code in a loop, waiting
   while (!*valuep)
     ; // 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 (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->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
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 not expect
signals to be ignored by default.

=item $async->block

=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 ($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)