NAME
====

epoll - I/O event notification facility

SYNOPSIS
========

    use epoll;

    my $epoll = epoll.new(maxevents => 1); # 1 is default

    $epoll.add($file-descriptor, :in, :out, :priority, :edge-triggered);

    # timeout in milliseconds, default -1 = block forever
    for $epoll.wait(:2000timeout)
    {
        say "{.fd} is ready for reading" if .in;
        say "{.fd} is ready for writing" if .out;
    }

    # Or use chained calls:

    for epoll.new.add(0, :in).wait
    {
        say "ready to read on {.fd}" if .in;
    }

DESCRIPTION
===========

Simple low level interface around the Linux `epoll(7)` I/O event notification facility. It can monitor multiple file descriptors to see if I/O is possible on any of them. Mainly useful for interfacing with other NativeCall modules, since Perl itself has a rich I/O system. If you really want to use this with Perl `IO::Handle`s, you can use `native-descriptor()` to get a suitable descriptor.

class **epoll**
---------------

  * method **new**(:$maxevents = 1)

Create a new epoll object. Maxevents is the maximum number of events that can be returned from a single call to wait.

  * method **add**(int32 $file-descriptor, ...event flags...)

    Flags:

<table>
  <tr>
    <td>:in</td>
    <td>EPOLLIN</td>
    <td>ready for read</td>
  </tr>
  <tr>
    <td>:out</td>
    <td>EPOLLOUT</td>
    <td>ready for write</td>
  </tr>
  <tr>
    <td>:priority</td>
    <td>EPOLLPRI</td>
    <td>urgent data available for read</td>
  </tr>
  <tr>
    <td>:edge-triggered</td>
    <td>EPOLLET</td>
    <td>Edge Triggered</td>
  </tr>
  <tr>
    <td>:one-shot</td>
    <td>EPOLLONESHOT</td>
    <td>Disables after 1 event</td>
  </tr>
  <tr>
    <td>:mod</td>
    <td>EPOLL_CTL_MOD</td>
    <td>Modify an existing file descriptor</td>
  </tr>
</table>

:mod is equivalent to EPOLL_CTL_MOD to change the events for a file descriptor already added. It will also re-enable a file descriptor disabled by :one-shot mode.

For convenience, always returns the object itself, so you can chain calls.

  * method **remove**(int32 $file-descriptor)

Remove a file descriptor previously added.

  * method **wait**(int32 :$timeout = -1)

Wait for 1 or more events to occur on the add()ed file descriptors. You can specify an optional timeout in milliseconds.

Returns a List of up up to $maxevents **epoll-event**s.

class **epoll-event**
---------------------

  * method int32 **fd**()

The file descriptor for the event.

  * method uint32 **events**()

A bitmask of the events that occurred. You can check them like this:

if $event.events +& EPOLLIN {...}

or use the much easier:

  * method Bool **in**()

Ready to read

  * method Bool **out**()

Ready to write

EXCEPTIONS
----------

Throws Ad-hoc exceptions for any errors.

(Should save errno, and make real Exceptions -- patches welcome!)

NOTE
----

epoll is a Linux specific mechanism, and is typically not available on other architectures.

LICENSE
=======

Copyright © 2017 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. No copyright is claimed in the United States under Title 17, U.S.Code. All Other Rights Reserved.