Home Contents | # event:add | Event | Core4 Lua Event System

## SYNOPSIS

#include <lua/poll.lh>

1. evh = app:add(fd, callback [, events])
2. function callback(evh, fd, revents) ...

## DESCRIPTION

Adds an event handler for generic file descriptor events. The argument fd specifies a generic file descriptor, e.g. as returned by rawio:fd(). Whenever an event happens on this file descriptor, the callback function is called. Reported events are selected with the events parameter, which is a logical or of the following values:

POLLIN | Data can be read from the file descriptor.
POLLOUT | Data can be written to the file descriptor.

The default value for events is POLLIN.

This function is mostly used for receiving data from a serial port or network socket.

When the callback is called, the parameter revents contains a logical or of all events that are pending and have been asked for when calling app:add().

After adding, the event handler is enabled and performs as described. It can be disabled and enabled at runtime by calling its evh:disable() and evh:enable() methods.

## RETURN VALUE

An event handler instance. The returned handler has a single function: evh:close(), which discards the handler and stops event processing.

## NOTES

Callbacks are called from within event:poll().

The file descriptor should not be in blocking mode when handled by the event system. The blocking mode can be disabled using rawio:blocking().

If you application seems to hang mysteriously, check if you have event handlers running on file descriptors in blocking mode.

## EXAMPLE

The following code will print lines entered at the console.
> > > > > > > > > > > > > > >
app = event.new() stdin = rawio.attach(0) stdin:blocking(false) function stdin_pending() for line in stdin:lines() do print ("LINE: ", line) end end evh = app:add(stdin:fd(), stdin_pending) while true do app:poll() end

## SEE ALSO

event.new, event:pause, event:poll, event:reset, event:shell, event:timer, evh:enable, evh:disable, evh:close