This is a library for watching file descriptors for events. It is designed to provide a simpler and lower-level API than libevent.


The module exposes a single new() function that creates a new state. It takes no arguments.

State methods

The state has three methods to manage which FDs to watch; :add(), :set() and :del().

All three take an FD number (integer) as first argument and except for :del() take booleans that signal interest in the FD becoming readable and/or writable, respectively.

All three return either a boolean true for success or a tripplet of nil, a textual error and an error code.

Then there is the :wait() method that waits until something happens to one of the registered FDs.

:add(fd, r, w)

Adds an FD to be watched. Arguments are the integer FD to watch and two optional booleans representing whether to watch for the FD becoming readable and/or writable.

:set(fd, r, w)

Changes which events to watch for. Arguments are the same as for :add().


Stops watching a FD. Takes no arguments beyond the integer FD.


Waits (blocking) until one or more FDs have pending events, or the amount of time given in the timeout argument has passed.

When a pending event that is watched for happens, :wait() returns a triplet consisting of the integer FD number the event happened to and two booleans matching the arguments to :add() and :set(), i.e. whether the FD is readable and/or writable.

If the timeout is reached, it returns nil and the string "timeout".


This method only exists if util.poll is built on Linux with the epoll API. It returns the epoll FD, which can be watched like any other FD.