“Event driven software improves concurrency” -- Dave Zarzycki, Apple
The C API to libuEv, listed in uev/uev.h, handles three different
types of events: I/O (pipes, sockets, message queues, etc.), timers, and
signals. The Summary details a slight caveat on signals.
Notice the lack of support for regular files and directories. This is
a limitation of the underlying Linux epoll interface which will return
EPERM for regular files. Except for the special case when stdin is
redirected from the command line. See examples/redirect.c for more on
this particular case.
Timers can be either relative, timeout in milliseconds, or absolute with
a time given in time_t, see mktime() et al. Absolute timers are
called cron timers and their callbacks get an UEV_HUP error event if
the wall clock changes, either via NTP or user input.
NOTE: On some systems, embedded in particular, time_t is a 32-bit
integer that wraps around in the year 2038. A GLIBC workaround
(-D_TIME_BITS=64) protects those systems, but users of other C
libraries have no known workarounds. It is strongly recommended to
use relative timers as often as possible.
/*
* Callback example, arg comes from the watcher's *_init() function,
* w->fd holds the file descriptor or socket, and events is set by
* libuEv to indicate status: UEV_READ and/or UEV_WRITE with any of
* the optional UEV_HUP, UEV_RDHUP, or UEV_PRI for urgent read data.
*
* Note: UEV_ERROR may be returned for any watcher and must be checked
* by all callbacks. I/O watchers may also need to check UEV_HUP.
* Appropriate action, e.g. restart the watcher, is up to the
* application and is thus delegated to the callback.
*/
void callback (uev_t *w, void *arg, int events);
/* Event loop: Notice the use of flags! */
int uev_init (uev_ctx_t *ctx);
int uev_init1 (uev_ctx_t *ctx, int maxevents);
int uev_exit (uev_ctx_t *ctx);
int uev_run (uev_ctx_t *ctx, int flags); /* UEV_NONE, UEV_ONCE, and/or UEV_NONBLOCK */
/* I/O watcher: fd *MUST* be non-blocking!
* events combination of the main flags: UEV_READ, UEV_WRITE,
* UEV_EDGE, UEV_ONESHOT
*/
int uev_io_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int fd, int events);
int uev_io_set (uev_t *w, int fd, int events);
int uev_io_start (uev_t *w);
int uev_io_stop (uev_t *w);
/* Timer watcher: schedule a relative timer, timeout (must be non-zero) and period in milliseconds */
int uev_timer_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int timeout, int period);
int uev_timer_set (uev_t *w, int timeout, int period); /* Change timeout or period */
int uev_timer_start (uev_t *w); /* Restart a stopped timer */
int uev_timer_stop (uev_t *w); /* Stop a timer */
/* Cron watcher: schedule an absolute timer, when and period in time_t seconds */
int uev_cron_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, time_t when, time_t period);
int uev_cron_set (uev_t *w, int when, time_t period); /* Change when or period */
int uev_cron_start (uev_t *w); /* Restart a stopped cron */
int uev_cron_stop (uev_t *w); /* Stop a cron */
/* Signal watcher: signo is the signal to wait for, e.g., SIGTERM */
int uev_signal_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int signo);
int uev_signal_set (uev_t *w, int signo); /* Change signal to wait for */
int uev_signal_start(uev_t *w); /* Restart a stopped signal watcher */
int uev_signal_stop (uev_t *w); /* Stop signal watcher */
/* Generic event watcher, post events for later processing, or from forked child */
int uev_event_init (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg);
int uev_event_post (uev_t *w);
int uev_event_stop (uev_t *w);To monitor events the developer first creates an event context, this
is achieved by calling uev_init() with a pointer to a (thread) local
uev_ctx_t variable.
uev_ctx_t ctx;
uev_init(&ctx);For each event to monitor, be it a signal, cron/timer or a file/network
descriptor, a watcher must be registered with the event context. The
watcher, an uev_t, is registered by calling the event type's _init()
function with the uev_ctx_t context, the callback, and an optional
argument.
Here is a signal example:
void cleanup_exit(uev_t *w, void *arg, int events)
{
if (UEV_ERROR == events)
puts("Ignoring signal watcher error ...");
else
printf("Got signal (signo %d) from PID %d\n",
w->siginfo.ssi_signo, w->siginfo.ssi_pid);
/* Graceful exit, with optional cleanup ... */
uev_exit(w->ctx);
}
int main(void)
{
uev_t sigterm_watcher;
.
.
uev_signal_init(&ctx, &sigterm_watcher, cleanup_exit, NULL, SIGTERM);
.
.
}Notice that the callback must be prepared to handle UEV_ERROR. I/O
watchers in particular, but also timer watchers, must be restarted if
required by the application. libuEv automatically tries to restart a
signal watcher, but should that fail the callback will return error as
well.
I/O watchers should also check for UEV_HUP, preferably when handling
any short read() or write() system calls. A short read on a socket
may be due to the remote end having performed a shutdown(). This is
signaled to the callback using UEV_HUP in the events mask.
When all watchers are registered, call the event loop with uev_run()
and the argument to the event context. The flags parameter can be
used to integrate libuEv into another event loop.
In this example we set flags to none:
result = uev_run(&ctx, UEV_NONE);With flags set to UEV_ONCE the event loop returns as soon as it has
served the first event. If flags is set to UEV_ONCE | UEV_NONBLOCK
the event loop returns immediately if no event is available.
if (result < 0)
errx(result, "Unrecoverable event loop error, error %d", result);
If the call to uev_run() fails you should notify the user somehow.
libuEv fails if there is an invalid pointer, if uev_init() was not
called, or recurring epoll() errors thare are impossible to recover
from should occur. This is true for individual watchers as well, in
particular signal and timer watchers which can fail in miserable ways.
Note: libuEv handles many types of errors, stream close, or peer shutdowns internally, but also lets the callback run. This is useful for stateful connections to be able to detect EOF.
-
Set up an event context with
uev_init() -
Register event callbacks with the event context using
uev_io_init(),uev_signal_init()oruev_timer_init() -
Make sure callbacks checks their
eventsmask and handles:UEV_ERROR, e.g. I/O watchers must be restartedUEV_HUP, reading any remaining data on the descriptor
In both of these cases the watcher is stopped by libuEv. On HUP the descriptor/connection must be reopened and the watcher reinitialized with
uev_io_set(), if required by the application. -
Start the event loop with
uev_run() -
Exit the event loop with
uev_exit(), possibly from a callback
Note 1: Make sure to use non-blocking stream I/O! Most hard to find bugs in event driven applications are due to sockets and files being opened in blocking mode. Be careful out there!
Note 2: When closing a descriptor or socket, make sure to first stop your watcher, if possible. This will help prevent any nasty side effects on your program.
Note 3: a certain amount of care is needed when dealing with APIs
that employ signalfd. If your application use system() you replace
that with fork(), and then in the child, unblock all signals blocked
by your parent process, before you run exec(). This because Linux
does not unblock signals for your children, and neither does most
(all?) C-libraries. See the finit project's implementation of
run() for an example of this. For more details on this issue, see
this article at lwn.net.
libuEv is by default installed as a library with a few header files, you should only ever need to include one:
#include <uev/uev.h>The output from the pkg-config tool holds no surprises:
$ pkg-config --libs --static --cflags libuev
-I/usr/local/include -L/usr/local/lib -luevThe prefix path /usr/local/ shown here is only the default. Use the
configure script to select a different prefix when installing libuEv.
For GNU autotools based projects, use the following in configure.ac:
# Check for required libraries
PKG_CHECK_MODULES([uev], [libuev >= 1.4.0])and in your Makefile.am:
proggy_CFLAGS = $(uev_CFLAGS)
proggy_LDADD = $(uev_LIBS)Here follows a very brief example to illustrate how one can use libuEv to act upon joystick input.
#include <err.h>
#include <errno.h>
#include <stdio.h>
#include <stdint.h>
#include <fcntl.h>
#include <unistd.h>
#include <uev/uev.h>
struct js_event {
uint32_t time; /* event timestamp in milliseconds */
int16_t value; /* value */
uint8_t type; /* event type */
uint8_t number; /* axis/button number */
} e;
/*
* Called on any joystick event
*
* Note: We handle errors here by exiting, for a background daemon with
* multiple watchers you may want another approach.
*/
static void joystick_cb(uev_t *w, void *arg, int events)
{
ssize_t cnt;
if (UEV_ERROR == events) {
/* Possibly joystick was unplugged */
warnx("Spurious problem with the joystick watcher, restarting.");
uev_io_start(w);
return;
}
cnt = read(w->fd, &e, sizeof(e));
if (cnt < 0) {
warn("Failed reading joystick event");
return;
}
if (cnt == 0 || UEV_HUP == events) {
warn("Joystick disconnected");
return;
}
switch (e.type) {
case 1:
printf("Button %d %s\n", e.number, e.value ? "pressed" : "released");
break;
case 2:
printf("Joystick axis %d moved, value %d!\n", e.number, e.value);
break;
}
}
int main(void)
{
uev_ctx_t ctx;
uev_t js;
int fd;
fd = open("/dev/input/js0", O_RDONLY, O_NONBLOCK);
if (fd < 0)
errx(errno, "Cannot find a joystick attached.");
uev_init(&ctx);
uev_io_init(&ctx, &js, joystick_cb, NULL, fd, UEV_READ);
puts("Starting, press Ctrl-C to exit.");
return uev_run(&ctx, 0);
}To build the example, follow installation instructions below, then save
the code as joystick.c and call GCC
$ gcc `pkg-config --libs --static --cflags libuev` -o joystick joystick.cAlternatively, call the Makefile with make joystick from
the unpacked libuEv distribution.
More complete and relevant example uses of libuEv is the FTP/TFTP
server uftpd, and the Linux /sbin/init replacement finit.
Both successfully employ libuEv.
Also see the bench.c program (make bench from within the
library) for reference benchmarks against libevent and
libev.