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. The signals can be specified either as names (e.g., INT) or as numbers. See man 2 epoll_pwait for why you might want to do this. (Note that Perl doesn’t really expect you to block signals directly, so this may screw things up for you in weird ways. If in doubt, avoid this option.)

The return is a list of hash references, one for each received event. Each hash reference is:

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

• events - Corresponds to the same-named 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.