Bump version for v1.6.0 release

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

API.md

@@ -0,0 +1,283 @@
+API Documentation
+=================
+
+* [Introduction](#introduction)
+* [Overview](#overview)
+  * [Create an Event Context](#create-an-event-context)
+  * [Register an Event Watcher](#register-an-event-watcher)
+  * [Start Event Loop](#start-event-loop)
+  * [Summary](#summary)
+* [Using -luev](#using--luev)
+* [Joystick Example](#joystick-example)
+
+
+Introduction
+------------
+
+The C API to [libuEv][], listed in `uev/uev.h`, handles three different
+types of events: I/O (files, sockets, message queues, etc.), timers, and
+signals.  The [Summary](#summary) details a slight caveat on signals.
+
+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.
+
+
+Overview
+--------
+
+```C
+/*
+ * 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.
+ */
+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_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 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 */
+```
+
+
+### Create an Event Context
+
+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.
+
+```C
+uev_ctx_t ctx;
+
+uev_init(&ctx);
+```
+
+
+### Register an Event Watcher
+
+For each event to monitor, be it a signal, timer or file 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:
+
+```C
+void cleanup_exit(uev_t *w, void *arg, int events)
+{
+    /* 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);
+    .
+    .
+}
+```
+
+
+### Start Event Loop
+
+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:
+
+```C
+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.
+
+**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.
+
+### Summary
+
+1. Set up an event context with `uev_init()`
+2. Register event callbacks with the event context using
+   `uev_io_init()`, `uev_signal_init()` or `uev_timer_init()`
+3. Start the event loop with `uev_run()`
+4. 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][6] project's implementation of
+  `run()` for an example of this.  For more details on this issue, see
+  [this article][4] at [lwn.net](http://lwn.net).
+
+
+Using -luev
+-----------
+
+LibuEv is by default installed as a library with a few header files, you
+should only ever need to include one:
+
+```C
+#include <uev/uev.h>
+```
+
+The output from the `pkg-config` tool holds no surprises:
+
+```sh
+$ pkg-config --libs --static --cflags libuev
+-I/usr/local/include -L/usr/local/lib -luev
+```
+
+The 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`:
+
+```sh
+# Check for required libraries
+PKG_CHECK_MODULES([uev], [libuev >= 1.4.0])
+```
+
+and in your `Makefile.am`:
+
+```sh
+proggy_CFLAGS = $(uev_CFLAGS)
+proggy_LDADD  = $(uev_LIBS)
+```
+
+
+Joystick Example
+----------------
+
+Here follows a very brief example to illustrate how one can use libuEv
+to act upon joystick input.
+
+```C
+#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;
+
+static void joystick_cb(uev_t *w, void *arg, int events)
+{
+    read(w->fd, &e, sizeof(e));
+
+    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)
+{
+    int fd;
+    uev_t watcher;
+    uev_ctx_t ctx;
+
+    fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
+    if (fd < 0)
+        errx(errno, "Cannot find a joystick attached.");
+
+    uev_init(&ctx);
+    uev_io_init(&ctx, &watcher, 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
+
+```sh
+$ gcc `pkg-config --libs --static --cflags libuev` -o joystick joystick.c
+```
+
+Alternatively, call the `Makefile` with <kbd>make joystick</kbd> from
+the unpacked [libuEv][] distribution.
+
+More complete and relevant example uses of [libuEv][] is the FTP/TFTP
+server [uftpd][5], and the Linux `/sbin/init` replacement [finit][6].
+Both successfully employ [libuEv][].
+
+Also see the `bench.c` program (<kbd>make bench</kbd> from within the
+library) for [reference benchmarks][7] against [libevent][1] and
+[libev][2].
+
+[1]:      http://libevent.org
+[2]:      http://software.schmorp.de/pkg/libev.html
+[4]:      http://lwn.net/Articles/415684/
+[5]:      https://github.com/troglobit/uftpd
+[6]:      https://github.com/troglobit/finit
+[7]:      http://libev.schmorp.de/bench.html
+[LibuEv]: https://github.com/troglobit/libuev
+[GLIBC workaround]: https://sourceware.org/glibc/wiki/Y2038ProofnessDesign

ChangeLog.md

@@ -3,6 +3,19 @@ Change Log
 
 All notable changes to the project are documented in this file.
 
+
+[v1.6.0][] - 2017-09-18
+-----------------------
+
+### Changes
+- Support for edge triggered and oneshot event types
+- Add `make package` build target to trigger a `.deb` package build
+- Support 64 bit `time_t` on 32 bit GLIBC systems
+
+### Fixes
+- `bench.c`: Use `signal.h`, not non-standard `sys/signal.h`
+
+
 [v1.5.2][] - 2016-11-27
 -----------------------
 

LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
-Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile.am

@@ -1,23 +1,12 @@
 ACLOCAL_AMFLAGS     = -I m4
+SUBDIRS             = src tests
+DIST_SUBDIRS        = src examples tests
+doc_DATA            = API.md README.md LICENSE
+EXTRA_DIST          = API.md README.md LICENSE AUTHORS ChangeLog.md
 
-lib_LTLIBRARIES     = libuev.la
-libuev_la_SOURCES   = uev.c io.c timer.c signal.c cron.c
-libuev_la_CPPFLAGS  = -D_GNU_SOURCE
-libuev_la_CFLAGS    = -W -Wall -Wextra
-libuev_la_LDFLAGS   = $(AM_LDFLAGS) -version-info 1:2:0
-
-noinst_PROGRAMS     = bench
-bench_CPPFLAGS      = -D_GNU_SOURCE
-bench_LDADD         = libuev.la
-
-pkgconfigdir        = $(libdir)/pkgconfig
-pkgincludedir       = $(includedir)/uev
-pkgconfig_DATA      = libuev.pc
-pkginclude_HEADERS  = uev.h private.h queue.h
-doc_DATA            = README.md LICENSE
-EXTRA_DIST          = README.md LICENSE AUTHORS ChangeLog.md
-DIST_SUBDIRS        = examples tests
-SUBDIRS             = tests
+## Generate .deb package
+package:
+	@dpkg-buildpackage -uc -us -B
 
 ## Generate MD5 checksum file
 MD5 = md5sum

README.md

@@ -4,18 +4,19 @@ libuEv | Simple event loop for Linux
 
 
 * [Introduction](#introduction)
-* [API](#api)
-  * [Create an Event Context](#create-an-event-context)
-  * [Register an Event Watcher](#register-an-event-watcher)
-  * [Start Event Loop](#start-event-loop)
-  * [Summary](#summary)
-* [Using -luev](#using--luev)
-* [Joystick Example](#joystick-example)
+* [API](API.md#overview)
+  * [Create an Event Context](API.md#create-an-event-context)
+  * [Register an Event Watcher](API.md#register-an-event-watcher)
+  * [Start Event Loop](API.md#start-event-loop)
+  * [Summary](API.md#summary)
+* [Using -luev](API.md#using--luev)
+* [Joystick Example](API.md#joystick-example)
 * [Build & Install](#build--install)
-* [Background](#background)
 * [Origin & References](#origin--references)
 
 
+> “Event driven software improves concurrency” -- [Dave Zarzycki, Apple][]
+
 Introduction
 ------------
 
@@ -25,334 +26,72 @@ Introduction
 small size overhead impact of the library.
 
 Experienced developers may appreciate that [libuEv][] is built on top of
-modern Linux APIs: epoll, timerfd and signalfd.  Note however, a certain
-amount of care is needed when dealing with APIs that employ signalfd.
-For details, see [this article][4] at [lwn.net](http://lwn.net).
-
-> “Event driven software improves concurrency” -- [Dave Zarzycki, Apple][]
+modern Linux APIs: epoll, timerfd and signalfd.
 
 
-API
----
+Example
+-------
 
-The C API to [libuEv][], listed in `uev/uev.h`, handles three different
-types of events: I/O (files, sockets, message queues, etc.), timers, and
-signals.  The [Summary](#summary) details a slight caveat on signals.
-
-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 systems in particular, `time_t` is a
-32-bit integer that wraps around in the year 2038.  [libuEv][] cannot
-protect you against this problem, unfortunately.
+The library documentation is available as a [separate document](API.md).
 
 ```C
+#include <stdio.h>
+#include <uev/uev.h>
 
-    /*
-     * 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_HUP, UEV_READ and/or UEV_WRITE
-     */
-    void callback       (uev_t *w, void *arg, int events);
+static void cb(uev_t *w, void *arg, int events)
+{
+	puts("Every other second");
+}
 
-    /* Event loop:      Notice the use of flags! */
-    int uev_init        (uev_ctx_t *ctx);
-    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 is non-blocking, events is UEV_READ and/or UEV_WRITE */
-    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 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 */
+int main(void)
+{
+	uev_t timer;
+	uev_ctx_t ctx;
 
+	uev_init(&ctx);
+	uev_timer_init(&ctx, &timer, cb, NULL, 2 * 1000, 0);
+
+	return uev_run(&ctx, 0);
+}
 ```
 
 
-### Create an Event Context
-
-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.
-
-```C
-
-    uev_ctx_t ctx;
-    
-    uev_init(&ctx);
-
-```
-
-
-### Register an Event Watcher
-
-For each event to monitor, be it a signal, timer or file 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:
-
-```C
-
-    void cleanup_exit(uev_t *w, void *arg, int events)
-    {
-        /* 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);
-		.
-		.
-		.
-	}
-
-```
-
-
-### Start Event Loop
-
-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:
-
-```C
-
-    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.
-
-**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.
-
-### Summary
-
-1. Set up an event context with `uev_init()`
-2. Register event callbacks with the event context using
-   `uev_io_init()`, `uev_signal_init()` or `uev_timer_init()`
-3. Start the event loop with `uev_run()`
-4. 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:** As mentioned above, a certain amount of care is needed when
-dealing with 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][6] project's implementation of `run()` for
-an example of this.
-
-
-Using -luev
------------
-
-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 -luev
-
-The 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)
-
-
-Joystick Example
-----------------
-
-Here follows a very brief example to illustrate how one can use libuEv
-to act upon joystick input.
-
-```C
-
-    #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;
-    
-    static void joystick_cb(uev_t *w, void *arg, int events)
-    {
-        read(w->fd, &e, sizeof(e));
-    
-        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)
-    {
-        int fd;
-        uev_t watcher;
-        uev_ctx_t ctx;
-    
-        fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
-        if (fd < 0)
-            errx(errno, "Cannot find a joystick attached.");
-    
-        uev_init(&ctx);
-        uev_io_init(&ctx, &watcher, 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.c
-
-Alternatively, call the `Makefile` with <kbd>make joystick</kbd> from
-the unpacked [libuEv][] distribution.
-
-More complete and relevant example uses of [libuEv][] is the FTP/TFTP
-server [uftpd][5], and the Linux `/sbin/init` replacement [finit][6].
-Both successfully employ [libuEv][].
-
-Also see the `bench.c` program (<kbd>make bench</kbd> from within the
-library) for [reference benchmarks][7] against [libevent][1] and
-[libev][2].
-
-
 Build & Install
 ---------------
 
-The library is built for and developed on GNU/Linux systems, patches to
-support *BSD and its [kqueue][] interface are most welcome.
-
 libuEv use the GNU configure and build system.  To try out the bundled
 examples, use the `--enable-examples` switch to the `configure` script.
+There is also a limited unit test suite that can be useful to learn how
+the library works.
 
-    ./configure
-    make -j5
-    make test
-    sudo make install-strip
-    sudo ldconfig
+```sh
+./configure
+make -j5
+make test
+sudo make install-strip
+sudo ldconfig
+```
 
-The resulting .so file is ~14 kiB (<kbd>make install-strip</kbd>).
-
-
-Background
-----------
-
-> “Why an event loop, why not use threads?”
-
-With the advent of light-weight processes (threads) programmers these
-days have a [golden hammer](http://c2.com/cgi/wiki?GoldenHammer) they
-often swing without consideration.  Event loops and non-blocking I/O is
-often a far easier approach, as well as less error prone.
-
-The purpose of many applications is, with a little logic sprinkled on
-top, to act on network packets entering an interface, timeouts expiring,
-mouse clicks, or other types of events.  Such applications are often
-very well suited to use an event loop.
-
-Applications that need to churn massively parallel algorithms are more
-suitable for running multiple (independent) threads on several CPU
-cores.  However, threaded applications must deal with the side effects
-of concurrency, like race conditions, deadlocks, live locks, etc.
-Writing error free threaded applications is hard, debugging them can be
-even harder.
-
-Sometimes the combination of multiple threads *and* an event loop per
-thread can be the best approach, but each application of course needs to
-be broken down individually to find the most optimal approach.  Do keep
-in mind, however, that not all systems your application will run on have
-multiple CPU cores -- some small embedded systems still use a single CPU
-core, even though they run Linux, with multiple threads a program may
-actually run slower!  Always profile your program, and if possible, test
-it on different architectures.
+The resulting .so file is ~14 kiB.
 
 
 Origin & References
 -------------------
 
 [libuEv][] was originally based on [LibUEvent][8] by [Flemming Madsen][]
-but has been completely rewritten with a much clearer API.  Now more
-similar to the famous [libev][2] by [Mark Lehmann][].  Another small
-event library used for inspiration is the very small [Picoev][9] by
-[Oku Kazuho][].
+but has been completely rewritten to provide a cleaner API.  It is now
+more similar to the famous [libev][2] by [Mark Lehmann][].  Another
+small event library used for inspiration is the very small [picoev][9]
+by [Oku Kazuho][].
+
+[libuEv][] is developed and maintained by [Joachim Nilsson][].  It is
+built for and developed on GNU/Linux systems, patches to support *BSD
+and its [kqueue][] interface are most welcome.
 
-[libuEv][] is developed and maintained by [Joachim Nilsson][].
 
 [1]: http://libevent.org
 [2]: http://software.schmorp.de/pkg/libev.html
 [3]: http://unix.com/man-page/All/3x/XtDispatchEvent
-[4]: http://lwn.net/Articles/415684/
-[5]: https://github.com/troglobit/uftpd
-[6]: https://github.com/troglobit/finit
-[7]: http://libev.schmorp.de/bench.html
 [8]: http://code.google.com/p/libuevent/
 [9]: https://github.com/kazuho/picoev
 [Travis]:          https://travis-ci.org/troglobit/libuev
@@ -366,9 +105,3 @@ event library used for inspiration is the very small [Picoev][9] by
 [Joachim Nilsson]: http://troglobit.com
 [Flemming Madsen]: http://www.madsensoft.dk
 [Dave Zarzycki, Apple]: http://www.youtube.com/watch?v=cD_s6Fjdri8
-
-<!--
-  -- Local Variables:
-  --  mode: markdown
-  -- End:
-  -->

TODO.md

@@ -1,6 +1,8 @@
 LibuEv TODO
 ===========
 
+* Add standard UNIX backend with select() and timer_create()
+  See SMCRoute and toolbox for examples.
 * Port to *BSD kqueue API, http://en.wikipedia.org/wiki/Kqueue
   Also in UNIX Network Progamming, by W. Richard Stevens 3rd ed.
 * Restore Lua bindings now that libuEv itself has stabilized

configure.ac

@@ -1,10 +1,10 @@
-AC_INIT(libuev, 1.5.2, https://github.com/troglobit/libuev/issues)
+AC_INIT(libuev, 1.6.0, https://github.com/troglobit/libuev/issues)
 AM_INIT_AUTOMAKE([1.11 foreign no-dist-gzip dist-xz])
 AM_SILENT_RULES([yes])
 
-AC_CONFIG_SRCDIR(uev.c)
+AC_CONFIG_SRCDIR(src/uev.c)
 AM_CONFIG_HEADER(config.h)
-AC_CONFIG_FILES([Makefile libuev.pc examples/Makefile tests/Makefile])
+AC_CONFIG_FILES([Makefile src/libuev.pc src/Makefile examples/Makefile tests/Makefile])
 AC_CONFIG_MACRO_DIR([m4])
 
 AC_PROG_CC

debian/.gitignore

@@ -0,0 +1,8 @@
+tmp/*
+libuev/*
+libuev*
+autoreconf*
+debhelper*
+files
+!*.dirs
+!*.install

debian/README.debian

@@ -0,0 +1,14 @@
+libuEv for Debian
+-----------------
+
+This is the upstream pre-packaged version of libuEv.  It consists of two
+.deb packages: one with only the .so library and one -dev package with
+headers and the .a library for static linking.  It builds on any Debian
+based operating system, e.g.  Debian, Ubuntu, Linux Mint, etc.
+
+Recommended reading is the upstream README and API docs.
+
+     less /usr/share/doc/libuev-dev/README.md
+    zless /usr/share/doc/libuev-dev/API.md.gz
+
+ -- Joachim Nilsson <troglobit@gmail.com>  Thu, 21 Sep 18:10, 2017

debian/changelog

@@ -0,0 +1,18 @@
+libuev (1.6.0-1) unstable; urgency=medium
+
+  * Support for edge triggered and oneshot event types
+  * Support for 64 bit time_t on 32 bit GLIBC systems
+
+ -- Joachim Nilsson <troglobit@gmail.com>  Mon, 18 Sep 2017 07:49:23 +0200
+
+libuev (1.5.2-2) unstable; urgency=low
+
+  * Minor packaging fixes.
+
+ -- Joachim Nilsson <troglobit@gmail.com>  Sun, 12 Mar 2017 17:48:00 +0100
+
+libuev (1.5.2-1) unstable; urgency=low
+
+  * Initial release.
+
+ -- Joachim Nilsson <troglobit@gmail.com>  Mon, 28 Nov 2016 22:53:35 +0100

debian/clean

@@ -0,0 +1 @@
+config.log

debian/compat

@@ -0,0 +1 @@
+9

debian/control

@@ -0,0 +1,39 @@
+Source: libuev
+Priority: optional
+Maintainer: Joachim Nilsson <troglobit@gmail.com>
+Build-Depends: dpkg-dev (>= 1.14.9), debhelper (>= 9), dh-autoreconf
+Standards-Version: 3.9.6
+Section: libs
+Homepage: https://github.com/troglobit/libuev/
+Vcs-Git: https://github.com/troglobit/libuev.git
+Vcs-Browser: https://github.com/troglobit/libuev/
+
+Package: libuev-dev
+Priority: extra
+Section: libdevel
+Architecture: any
+Depends: ${misc:Depends}, libuev (= ${binary:Version})
+Description: static library, header files, and docs for libuev
+ Static library, header files, and documentation for libuev.
+ .
+ libuEv is a simple event loop in the style of the more established
+ libevent, libev and the venerable Xt(3) event loop. The u (micro) in the
+ name refers to both the small feature set and the small size overhead
+ impact of the library.
+ .
+ Experienced developers may appreciate that libuEv is built on top of
+ modern Linux APIs: epoll, timerfd and signalfd. Note however, a certain
+ amount of care is needed when dealing with APIs that employ signalfd.
+
+Package: libuev
+Architecture: any
+Depends: ${misc:Depends}, ${shlibs:Depends}
+Description: Lightweight event loop library
+ libuEv is a simple event loop in the style of the more established
+ libevent, libev and the venerable Xt(3) event loop. The u (micro) in the
+ name refers to both the small feature set and the small size overhead
+ impact of the library.
+ .
+ Experienced developers may appreciate that libuEv is built on top of
+ modern Linux APIs: epoll, timerfd and signalfd. Note however, a certain
+ amount of care is needed when dealing with APIs that employ signalfd.

debian/copyright

@@ -0,0 +1,26 @@
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Source: https.//github.com/troglobit/libuev/
+
+Files: *
+Copyright: 2013-2017 Joachim Nilsson <troglobit@gmail.com>
+License: MIT
+Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
+Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

debian/docs

@@ -0,0 +1,2 @@
+API.md
+README.md

debian/libuev-dev.dirs

@@ -0,0 +1,2 @@
+usr/lib
+usr/include

debian/libuev-dev.install

@@ -0,0 +1,6 @@
+usr/include/uev/uev.h
+usr/include/uev/private.h
+usr/include/uev/queue.h
+usr/lib/*/lib*.a
+usr/lib/*/lib*.so
+usr/lib/*/pkgconfig/lib*.pc

debian/libuev.dirs

@@ -0,0 +1 @@
+usr/lib

debian/libuev.install

@@ -0,0 +1 @@
+usr/lib/*/lib*.so.*

debian/rules

@@ -0,0 +1,10 @@
+#!/usr/bin/make -f           
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+%:
+	dh $@ --with autoreconf
+
+override_dh_compress:
+	dh_compress -A -X.md

debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

examples/joystick.c

@@ -1,6 +1,6 @@
 /* Simple example of how to use libuEv with Linux joystick API
  *
- * Copyright (c) 2014-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2014-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/Makefile.am

@@ -0,0 +1,14 @@
+lib_LTLIBRARIES     = libuev.la
+libuev_la_SOURCES   = uev.c io.c timer.c signal.c cron.c
+libuev_la_CPPFLAGS  = -D_GNU_SOURCE -D_TIME_BITS=64
+libuev_la_CFLAGS    = -W -Wall -Wextra
+libuev_la_LDFLAGS   = $(AM_LDFLAGS) -version-info 1:2:0
+
+noinst_PROGRAMS     = bench
+bench_CPPFLAGS      = -D_GNU_SOURCE
+bench_LDADD         = libuev.la
+
+pkgconfigdir        = $(libdir)/pkgconfig
+pkgincludedir       = $(includedir)/uev
+pkgconfig_DATA      = libuev.pc
+pkginclude_HEADERS  = uev.h private.h queue.h

src/README.md

@@ -0,0 +1 @@
+../API.md

src/bench.c

@@ -44,11 +44,11 @@
 
 #include <errno.h>
 #include <fcntl.h>
+#include <signal.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/resource.h>
-#include <sys/signal.h>
 #include <sys/socket.h>
 #include <sys/stat.h>
 #include <sys/time.h>

src/cron.c

@@ -1,7 +1,7 @@
 /* libuEv - Micro event loop library
  *
  * Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
- * Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/io.c

@@ -1,7 +1,7 @@
 /* libuEv - Micro event loop library
  *
  * Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
- * Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -33,7 +33,7 @@
  * @param cb      I/O callback
  * @param arg     Optional callback argument
  * @param fd      File descriptor to watch, or -1 to register an empty watcher
- * @param events  Requested events to watch for, a mask of %UEV_READ, %UEV_WRITE and %UEV_PRI
+ * @param events  Events to watch for: %UEV_READ, %UEV_WRITE, %UEV_EDGE, %UEV_ONESHOW
  *
  * @return POSIX OK(0) or non-zero with @param errno set on error.
  */
@@ -60,6 +60,10 @@ int uev_io_init(uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int fd, int e
  */
 int uev_io_set(uev_t *w, int fd, int events)
 {
+
+	if ((events & UEV_ONESHOT) && w->active)
+		return uev_watcher_rearm(w);
+
 	/* Ignore any errors, only to clean up anything lingering ... */
 	uev_io_stop(w);
 

src/private.h

@@ -38,7 +38,7 @@ typedef enum {
 } uev_type_t;
 
 /* Event mask, used internally only. */
-#define UEV_EVENT_MASK  (UEV_READ | UEV_WRITE | UEV_PRI | UEV_HUP)
+#define UEV_EVENT_MASK  (UEV_READ | UEV_WRITE | UEV_PRI | UEV_HUP | UEV_RDHUP | UEV_EDGE | UEV_ONESHOT)
 
 /* Main libuEv context type */
 typedef struct {
@@ -87,6 +87,7 @@ int uev_watcher_init  (uev_ctx_t *ctx, struct uev *w, uev_type_t type,
 int uev_watcher_start (struct uev *w);
 int uev_watcher_stop  (struct uev *w);
 int uev_watcher_active(struct uev *w);
+int uev_watcher_rearm (struct uev *w);
 
 #endif /* LIBUEV_PRIVATE_H_ */
 

src/signal.c

@@ -1,7 +1,7 @@
 /* libuEv - Micro event loop library
  *
  * Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
- * Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/timer.c

@@ -1,7 +1,7 @@
 /* libuEv - Micro event loop library
  *
  * Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
- * Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/uev.c

@@ -1,7 +1,7 @@
 /* libuEv - Micro event loop library
  *
  * Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
- * Copyright (c) 2013-2016  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2013-2017  Joachim Nilsson <troglobit()gmail!com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -133,6 +133,24 @@ int uev_watcher_active(uev_t *w)
 	return w->active;
 }
 
+/* Private to libuEv, do not use directly! */
+int uev_watcher_rearm(uev_t *w)
+{
+	struct epoll_event ev;
+
+	if (!w || w->fd < 0) {
+		errno = EINVAL;
+		return -1;
+	}
+
+	ev.events   = w->events | EPOLLRDHUP;
+	ev.data.ptr = w;
+	if (epoll_ctl(w->ctx->fd, EPOLL_CTL_MOD, w->fd, &ev) < 0)
+		return -1;
+
+	return 0;
+}
+
 /**
  * Create an event loop context
  * @param ctx  Pointer to an uev_ctx_t context to be initialized

src/uev.h

@@ -30,12 +30,15 @@
 /* Max. number of simulateneous events */
 #define UEV_MAX_EVENTS  10
 
-/* I/O events, for signals and timers revents will always be UEV_READ */
+/* I/O events, signal and timer revents are always UEV_READ */
 #define UEV_NONE        0
 #define UEV_READ        EPOLLIN
 #define UEV_WRITE       EPOLLOUT
 #define UEV_PRI         EPOLLPRI
 #define UEV_HUP         EPOLLHUP
+#define UEV_RDHUP       EPOLLRDHUP
+#define UEV_EDGE        EPOLLET
+#define UEV_ONESHOT     EPOLLONESHOT
 
 /* Run flags */
 #define UEV_ONCE        1
@@ -58,7 +61,11 @@ typedef struct uev {
 	uev_ctx_t      *ctx;
 } uev_t;
 
-/* Generic callback for watchers */
+/*
+ * Generic callback for watchers, @events holds %UEV_READ and/or %UEV_WRITE
+ * with optional %UEV_PRI (priority data available to read) and any of the
+ * %UEV_HUP and/or %UEV_RDHUP, which may be used to signal hang-up events.
+ */
 typedef void (uev_cb_t)(uev_t *w, void *arg, int events);
 
 /* Public interface */

tests/Makefile.am

@@ -13,4 +13,4 @@ check_PROGRAMS  = $(TESTS)
 # Ignore warnings about unused result, in e.g. write()
 CFLAGS          = -W -Wall -Wextra -Wno-unused-result
 CPPFLAGS        = -D_GNU_SOURCE
-LDADD           = -L../ ../libuev.la
+LDADD           = -L../src ../src/libuev.la

tests/check.h

@@ -7,7 +7,7 @@
 #include <time.h>
 #include <unistd.h>
 
-#include "../uev.h"
+#include "../src/uev.h"
 
 #define UNUSED(arg) arg __attribute__ ((unused))