NAME

Linux::Perl::epoll

SYNOPSIS

    my $epl = Linux::Perl::epoll->new();

    $epl->add( $fh, events => ['IN', 'ET'] );

    my @events = $epl->wait(
        maxevents => 3,
        timeout => 2,   #seconds
        sigmask => ['INT', 'TERM'], #optional
    );

    $epl->delete($fh);

DESCRIPTION

An interface to Linux’s “epoll” feature.

Note that older kernel versions may not support all of the functionality documented here. Check your system’s epoll documentation (i.e., man 7 epoll and the various system calls’ pages) for full details.

METHODS

CLASS->new( %OPTS )

Creates a new epoll instance. %OPTS are:

• flags - Currently only CLOEXEC is recognized.

• size - Optional, and only useful on pre-2.6.8 kernels. See main 2 epoll_create for more details.

CLASS->EVENT_NUMBER()

Returns a (constant) hash reference that cross-references event names and their numbers. This is useful, e.g., for parsing events from the return of wait().

The recognized event names are IN, OUT, RDHUP, PRI, ERR, and HUP.

OBJ->add( $FD_OR_FH, %OPTS )

Adds a listener to the epoll instance. $FD_OR_FH is either a Perl filehandle or a file descriptor number. %OPTS are:

• events - An array reference of events/switches. Each member is either a key from EVENT_NUMBER() or one of the following switches: ET, ONESHOT, WAKEUP, EXCLUSIVE. Your kernel may not support all of those; check man 2 epoll_ctl for details.

• data - Optional, an arbitrary number to store with the file descriptor. This defaults to the file descriptor because this is the obvious way to correlate an event with its filehandle; however, you can set your own numeric value here if you’d rather.

OBJ->modify( $FD_OR_FH, %OPTS )

Same arguments as add(); use this to update an existing epoll listener.

OBJ->delete( $FD_OR_FH )

Removes an epoll listener.

@events = OBJ->wait( %OPTS )

Waits for one or more events on the epoll. %OPTS are:

• maxevents - The number of events to listen for.

• timeout - in seconds

• sigmask - Optional, an array of signals to block as part of this function call. Give signals either as names (e.g., INT) or as numbers. See man 2 epoll_pwait for why you might want to do this. Also see Linux::Perl::sigprocmask for an easy, light way to block signals.

The return is a list of key-value pairs. Each pair is:

• The data number given in add()—or, if you didn’t set a custom data value, the file descriptor associated with the event.

• A number that corresponds to the events array given in add(), but to optimize performance this is returned as a single number. Check for specific events by iterating through the EVENT_NUMBER() hash reference.

You can generally assign this list into a hash for easy parsing, as long as you do not specify non-unique custom data values.