NAME

    IO::Ppoll - Object interface to the ppoll() system call

SYNOPSIS

       use IO::Ppoll qw( POLLIN POLLOUT );
       use POSIX qw( sigprocmask SIG_BLOCK SIGHUP );
    
       my $ppoll = IO::Ppoll->new();
       $ppoll->mask( $input_handle => POLLIN );
       $ppoll->mask( $output_handle => POLLOUT );
    
       $SIG{HUP} = sub { print "SIGHUP happened\n"; };
       sigprocmask( SIG_BLOCK, POSIX::SigSet->new( SIGHUP ), undef );
    
       # If a SIGHUP happens, it can only happen during this poll
       $ppoll->poll( $timeout );
    
       $input_ev = $poll->events( $input_handle );

DESCRIPTION

    IO::Ppoll is a simple interface to the ppoll() system call. It provides
    an interface that is drop-in compatible with IO::Poll. The object
    stores a signal mask that will be in effect during the actual ppoll()
    system call and has additional methods for manipulating the signal
    mask.

    The ppoll() system call atomically switches the process's signal mask
    to that provided by the call, waits identically to poll(), then
    switches it back again. This allows a program to safely wait on either
    file handle IO or signals, without needing such tricks as a
    self-connected pipe or socket.

    The usual way in which this is used is to block the signals the
    application is interested in during the normal running of code.
    Whenever the ppoll() wait is entered the process signal mask will be
    switched to that stored in the object. If there are any pending
    signals, the kernel will then deliver them and make ppoll() return -1
    with errno set to EINTR. If no signals are pending, it will wait as a
    normal poll() would. This guarantees the signals will only be delivered
    during the ppoll() wait, when it would be safe to do so.

    The ppoll() system call was originally implemented on Linux, but has
    also been implemented on other operating systems such as many of the
    BSD-derived ones. This module attempts not to be Linux-specific, and so
    should work on any OS where the system call is available.

CONSTRUCTOR

 new

       $ppoll = IO::Ppoll->new();

    Returns a new instance of an IO::Ppoll object. It will contain no file
    handles and its signal mask will be empty.

METHODS

 mask

       $mask = $ppoll->mask( $handle );

    Returns the current mask bits for the given IO handle

       $ppoll->mask( $handle, $newmask );

    Sets the mask bits for the given IO handle. If $newmask is 0, the
    handle will be removed.

 mask_add

 mask_del

       $ppoll->mask_add( $handle, $addmask );
    
       $ppoll->mask_del( $handle, $delmask );

    Since version 0.12.

    Convenient shortcuts to setting or clearing one or more bits in the
    mask of a handle. Equivalent, respectively, to the following lines

       $ppoll->mask( $handle, $ppoll->mask( $handle ) | $addmask );
    
       $ppoll->mask( $handle, $ppoll->mask( $handle ) & ~$delmask );

    Specifically note that $maskbits contains bits to remove from the mask.

 poll

       $ret = $ppoll->poll( $timeout );

    Call the ppoll() system call. If $timeout is not supplied then no
    timeout value will be passed to the system call. Returns the result of
    the system call, which is the number of filehandles that have non-zero
    events, 0 on timeout, or -1 if an error occurred (including being
    interrupted by a signal). If -1 is returned, $! will contain the error.

 events

       $bits = $ppoll->events( $handle );

    Returns the event mask which represents the events that happened on the
    filehandle during the last call to poll().

 remove

       $ppoll->remove( $handle );

    Removes the handle from the list of file descriptors for the next poll.

 handles

       @handles = $ppoll->handles( $bits );

    Returns a list of handles. If $bits is not given then all of the
    handles will be returned. If $bits is given then the list will only
    contain handles which reported at least one of the bits specified
    during the last poll() call.

 sigmask

       $sigset = $ppoll->sigmask;

    Returns the POSIX::SigSet object in which the signal mask is stored.
    Since this is a reference to the object the IO::Ppoll object uses, any
    modifications made to it will be reflected in the signal mask given to
    the ppoll() system call.

       $ppoll->sigmask( $newsigset );

    Sets the POSIX::SigSet object in which the signal mask is stored.
    Usually this is not required, as a new IO::Ppoll is initialised with an
    empty set, and the sigmask_add() and sigmask_del() methods can be used
    to modify it.

 sigmask_add

       $ppoll->sigmask_add( @signals );

    Adds the given signals to the signal mask. These signals will be
    blocked during the poll() call.

 sigmask_del

       $ppoll->sigmask_del( @signals );

    Removes the given signals from the signal mask. These signals will not
    be blocked during the poll() call, and may be delivered while poll() is
    waiting.

 sigmask_ismember

       $present = $ppoll->sigmask_ismember( $signal );

    Tests if the given signal is present in the signal mask.

SEE ALSO

      * IO::Poll - Object interface to system poll call

      * ppoll(2) - wait for some event on a file descriptor (Linux
      manpages)

      * IO::Async::Loop::Ppoll - a Loop using an IO::Ppoll object

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

