view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        signal => $signame_or_value
            When this parameter is specified, then the Async::Interrupt will
            hook the given signal, that is, it will effectively call
            "->signal (0)" each time 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.

        signal_hysteresis => $boolean
            Sets the initial signal hysteresis state, see the
            "signal_hysteresis" method, below.

        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 read again. Due to races, it is
            unlikely but possible that multiple octets are written. It is
            required that the file handles are both in nonblocking mode.

            The object will keep a reference to the file handles.

            This can be used to ensure that async notifications will
            interrupt event frameworks as well.

            Note that "Async::Interrupt" will create a suitable signal fd
            automatically when your program requests one, so you don't have
            to specify 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
            "Async::Interrupt::EventPipe" class to manage those.

        pipe_autodrain => $boolean
            Sets the initial autodrain state, see the "pipe_autodrain"
            method, below.

    ($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 $signal_arg, which is a "void *" cast to "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 "value" is passed to both C and Perl
        callback.

        $value must be in the valid range for a "sig_atomic_t", except 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 "value" is either the old or the new one. Due to the
        asynchronous nature of the code, the "value" can even be passed to
        two consecutive invocations of the callback.

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

        Note that it is often beneficial to just call "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

    $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).

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

    $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 "$async->block" the
        interrupt object, then register a read watcher on the "pipe_fileno"
        that calls "$async->handle".

        This disables asynchronous interruptions, but ensures that
        interrupts are handled by the event loop.

    $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 "SIG_IGN" in the signal handler and restore it just
        before handling the interruption.