Update ChangeLog and bump version for v1.4.0 release

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

.gitignore

@@ -4,6 +4,8 @@
 *.so
 *.so.*
 *.a
+*.la
+*.lo
 .deps
 .libs
 compile
@@ -22,4 +24,6 @@ ar-lib
 autom4te.cache
 bench
 test
-libuev*
+libuev*.tar.*
+libuev.pc
+!libuev.pc.in

ChangeLog

@@ -1 +0,0 @@
-ChangeLog.md

ChangeLog.md

@@ -4,14 +4,37 @@ Change Log
 All notable changes to the project are documented in this file.
 
 
+[v1.4.0][] - 2016-03-22
+-----------------------
+
+This release changes the header file namespace, which was silently
+introduced in [v1.2.1][].  Apologies for any problems this may cause!
+
+### Changes
+
+- Change namespace for header files: `libuev/` to `uev/`, e.g. using
+  `pkg-config` your C program must now `#include <uev/uev.h>`
+- Support for EPOLLPRI events for I/O watchers, thanks to Markus Svilans
+- Simplified joystick example
+- Updated README slightly
+
+
+[v1.3.1][] - 2016-02-02
+-----------------------
+
+### Fixes
+- Remove symlinks to Markdown files from GIT
+- Distribute and install Markdown files: README.md, etc.
+
+
 [v1.3.0][] - 2016-01-22
 -----------------------
 
 ### Changes
 - Change to GNU configure and build system
-- Default optimization is now -O2, not -Os, which can be a bit
+- Default optimization is now `-O2`, not `-Os`, which can be a bit
-  unpredictable with some cross compiler toolchains.  -O2 is
+  unpredictable with some cross compiler toolchains.  `-O2` is the
-  the tried and tested path, and default in autotools
+  tried and tested path, and default in autotools
 - Added `-Wextra` to the previous `-W -Wall`, drop `-Werror`
   which is supposed to be used by maintainer(s) only.
 
@@ -65,7 +88,7 @@ Minor bugfix release.
   called `private.h`.  This will hopefully make it easier to understand
   what a user of libuEv is allowed to play around with.  Thanks to @vonj
   for the discussions around this!
-- All builds of libuEv now default to use -fPIC, this bloats the code
+- All builds of libuEv now default to use `-fPIC`, this bloats the code
   slightly, but ensures that linking works for all use cases, withouth
   introducing unnecessary complexity.
 
@@ -195,7 +218,10 @@ v0.0.1 - 2012-03-17
 Lua users mailing list.
 
 
-[UNRELEASED]: https://github.com/troglobit/libuev/compare/v1.2.3...HEAD
+[UNRELEASED]: https://github.com/troglobit/libuev/compare/v1.4.0...HEAD
+[v1.4.0]: https://github.com/troglobit/libuev/compare/v1.3.1...v1.4.0
+[v1.3.1]: https://github.com/troglobit/libuev/compare/v1.3.0...v1.3.1
+[v1.3.0]: https://github.com/troglobit/libuev/compare/v1.2.3...v1.3.0
 [v1.2.3]: https://github.com/troglobit/libuev/compare/v1.2.2...v1.2.3
 [v1.2.2]: https://github.com/troglobit/libuev/compare/v1.2.1...v1.2.2
 [v1.2.1]: https://github.com/troglobit/libuev/compare/v1.2.0...v1.2.1

Makefile.am

@@ -1,6 +1,7 @@
 ACLOCAL_AMFLAGS     = -I m4
 
 lib_LTLIBRARIES     = libuev.la
+pkgincludedir       = $(includedir)/uev
 pkginclude_HEADERS  = uev.h private.h queue.h
 libuev_la_SOURCES   = uev.c io.c timer.c signal.c
 
@@ -12,8 +13,10 @@ libuev_la_CPPFLAGS  = -D_GNU_SOURCE
 libuev_la_CFLAGS    = -W -Wall -Wextra
 libuev_la_LDFLAGS   = $(AM_LDFLAGS) -version-info 1:0:0
 
-doc_DATA            = README LICENSE
+pkgconfigdir        = $(libdir)/pkgconfig
-#EXTRA_DIST          = README.md AUTHORS LICENSE ChangeLog.md
+pkgconfig_DATA      = libuev.pc
+doc_DATA            = README.md LICENSE
+EXTRA_DIST          = README.md LICENSE AUTHORS ChangeLog.md
 
 DIST_SUBDIRS        = examples
 SUBDIRS             = .

README

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

README.md

@@ -12,6 +12,7 @@ Table of Contents
   * [Register an Event Watcher](#register-an-event-watcher)
   * [Start Event Loop](#start-event-loop)
   * [Summary](#summary)
+* [Using -luev](#using--luev)
 * [Joystick Example](#joystick-example)
 * [Build & Install](#build--install)
 * [Origin & References](#origin--references)
@@ -59,19 +60,21 @@ modern Linux APIs: epoll, timerfd and signalfd.  Note, 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]
+> “Event driven software improves concurrency” -- [Dave Zarzycki, Apple][]
 
 
 API
 ---
 
-The C interface to [libuEv][] is very simple.  It handles three different
+The C interface to [libuEv][] is listed in `uev.h`.  It handles three
-types of events: I/O (files, sockets, message queues, etc.), timers, and
+different types of events: I/O (files, sockets, message queues, etc.),
-signals.  With a slight caveat on signals
+timers, and signals.  With a slight caveat on signals detailed below
+in the [Summary](#summary).
 
 ```C
 
-    /* Callback example, arg is passed from watcher's *_init()
+    /*
+     * Callback example, arg is passed from watcher's *_init()
      * w->fd holds the file descriptor, events is set by libuEv
      * to indicate if any of UEV_READ and/or UEV_WRITE is ready.
      */
@@ -102,6 +105,7 @@ signals.  With a slight caveat on signals
 
 ```
 
+
 ### Create an Event Context
 
 To monitor events the developer first creates an *event context*, this
@@ -188,20 +192,36 @@ opened in blocking mode.  Be careful out there!
   effects on your program.
 
 **Note 3:** As mentioned above, a certain amount of care is needed when
-dealing with signalfd.  This means that if your application, for
+dealing with signalfd.  If your application use `system()` you replace
-instance, uses `system()` you must redesign that to use `fork()`, and
+that with `fork()`, and then in the child, unblock all signals blocked
-then in the child, unblock all signals blocked by your parent process,
+by your parent process, before you run `exec()`.  This because Linux
-before you run `exec()`.  This because Linux does not unblock signals
+does not unblock signals for your children, and neither does most (all?)
-for your children, and neither does most (all?) C-libraries.  An example
+C-libraries.  See the [finit][6] project's implementation of `run()` for
-of this, from [finit][6], implementing `run()` as a better replacement
+an example of this.
-to `system()`, which sucks anyawy :)
+
+
+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.
 
 
 Joystick Example
 ----------------
 
-Here follows a very brief example to illustrate how one can use
+Here follows a very brief example to illustrate how one can use libuEv
-[libuEv][] to act upon joystick input.
+to act upon joystick input.
 
 ```C
 
@@ -211,55 +231,57 @@ Here follows a very brief example to illustrate how one can use
     #include <stdint.h>
     #include <fcntl.h>
     #include <unistd.h>
-    
+    #include <uev/uev.h>
-    #include "uev.h"
     
     struct js_event {
-    	uint32_t time;		/* event timestamp in milliseconds */
+        uint32_t time;      /* event timestamp in milliseconds */
-    	int16_t  value;		/* value */
+        int16_t  value;     /* value */
-    	uint8_t  type;		/* event type */
+        uint8_t  type;      /* event type */
-    	uint8_t  number;	/* axis/button number */
+        uint8_t  number;    /* axis/button number */
     } e;
     
     static void joystick_cb(uev_t *w, void *arg, int events)
     {
-    	read (w->fd, &e, sizeof(e));
+        read(w->fd, &e, sizeof(e));
     
-    	switch (e.type) {
+        switch (e.type) {
-    	case 1:
+        case 1:
-    		if (e.value) printf("Button %d pressed\n", e.number);
+            printf("Button %d %s\n", e.number, e.value ? "pressed" : "released");
-    		else 	     printf("Button %d released\n", e.number);
+            break;
-    		break;
     
-    	case 2:
+        case 2:
-    		printf("Joystick axis %d moved, value %d!\n", e.number, e.value);
+            printf("Joystick axis %d moved, value %d!\n", e.number, e.value);
-    		break;
+            break;
-    	}
+        }
     }
     
     int main(void)
     {
-    	int       fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
+        int fd;
-    	uev_t     js1_watcher;
+        uev_t watcher;
-    	uev_ctx_t ctx;
+        uev_ctx_t ctx;
     
-    	if (fd < 0)
+        fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
-    		errx(errno, "Cannot find a joystick attached.");
+        if (fd < 0)
+            errx(errno, "Cannot find a joystick attached.");
     
-    	uev_init(&ctx);
+        uev_init(&ctx);
-    	uev_io_init(&ctx, &js1_watcher, joystick_cb, NULL, fd, UEV_READ);
+        uev_io_init(&ctx, &watcher, joystick_cb, NULL, fd, UEV_READ);
     
-    	puts("Starting, press Ctrl-C to exit.");
+        puts("Starting, press Ctrl-C to exit.");
     
-    	return uev_run(&ctx, 0);
+        return uev_run(&ctx, 0);
     }
 
 ```
 
-To compile the program, save the code as `joystick.c` and call GCC with
+To build the example, follow installation instructions below, then save
-`gcc -o joystick joystick.c io.c timer.c signal.c main.c` from this
+the code as `joystick.c` and call GCC
-directory, skips using a Makefile altogether.  Alternatively, call the
+
-`Makefile` with <kbd>make joystick</kbd> from this directory.
+    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].
@@ -284,7 +306,7 @@ examples, use the `--enable-examples` switch to the `configure` script.
     make test
     make install
 
-The resulting .so file is ~14 kiB when stripped (`make install-strip`).
+The resulting .so file is ~14 kiB (<kbd>make install-strip</kbd>).
 
 
 Origin & References

TODO

@@ -1 +0,0 @@
-TODO.md

configure.ac

@@ -1,12 +1,12 @@
 # Use v2.61 for backwards compat with Ubuntu 12.04 LTS
 AC_PREREQ([2.61])
-AC_INIT(libuEv, 1.3.0, https://github.com/troglobit/libuev/issues, libuev)
+AC_INIT(libuEv, 1.4.0, https://github.com/troglobit/libuev/issues, libuev)
 AM_INIT_AUTOMAKE([1.11 foreign no-dist-gzip dist-xz])
 AM_SILENT_RULES([yes])
 
 AC_CONFIG_SRCDIR(uev.c)
 AM_CONFIG_HEADER(config.h)
-AC_CONFIG_FILES([Makefile examples/Makefile])
+AC_CONFIG_FILES([Makefile libuev.pc examples/Makefile])
 AC_CONFIG_MACRO_DIR([m4])
 
 AC_PROG_CC

examples/joystick.c

@@ -1,6 +1,6 @@
 /* Simple example of how to use libuEv with Linux joystick API
  *
- * Copyright (c) 2014-2015  Joachim Nilsson <troglobit()gmail!com>
+ * Copyright (c) 2014-2016  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
@@ -30,8 +30,6 @@
 
 #include "uev.h"
 
-#define UNUSED(arg) arg __attribute__ ((unused))
-
 struct js_event {
 	uint32_t time;		/* event timestamp in milliseconds */
 	int16_t  value;		/* value */
@@ -39,15 +37,14 @@ struct js_event {
 	uint8_t  number;	/* axis/button number */
 } e;
 
-static void joystick_cb(uev_t *w, void *UNUSED(arg), int UNUSED(events))
+static void joystick_cb(uev_t *w, void *arg, int events)
 {
-	if (read (w->fd, &e, sizeof(e)) < 0)
+	if (read(w->fd, &e, sizeof(e)) < 0)
 		errx(errno, "Failed reading joystick event");
 
 	switch (e.type) {
 	case 1:
-		if (e.value) printf("Button %d pressed\n", e.number);
+		printf("Button %d %s\n", e.number, e.value ? "pressed" : "released");
-		else 	     printf("Button %d released\n", e.number);
 		break;
 
 	case 2:
@@ -58,10 +55,11 @@ static void joystick_cb(uev_t *w, void *UNUSED(arg), int UNUSED(events))
 
 int main(void)
 {
-	int       fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
+	int fd;
-	uev_t     js1_watcher;
+	uev_t js1_watcher;
 	uev_ctx_t ctx;
 
+	fd = open("/dev/input/js1", O_RDONLY, O_NONBLOCK);
 	if (fd < 0)
 		errx(errno, "Cannot find a joystick attached.");
 
@@ -75,7 +73,7 @@ int main(void)
 
 /**
  * Local Variables:
- *  compile-command: "gcc -o joystick joystick.c io.o timer.o signal.o main.o"
+ *  compile-command: "make joystick"
  *  version-control: t
  *  indent-tabs-mode: t
  *  c-file-style: "linux"

io.c

@@ -34,7 +34,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 and %UEV_WRITE
+ * @param events  Requested events to watch for, a mask of %UEV_READ, %UEV_WRITE and %UEV_PRI
  *
  * @return POSIX OK(0) or non-zero with @param errno set on error.
  */

libuev.pc.in

@@ -0,0 +1,12 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@
+
+Name: @PACKAGE@
+Description: Simple event loop for Linux
+Version: @VERSION@
+Requires:
+Libs: -L${libdir} -luev
+Cflags: -I${includedir}
+

private.h

@@ -37,7 +37,7 @@ typedef enum {
 } uev_type_t;
 
 /* Event mask, used internally only. */
-#define UEV_EVENT_MASK  (UEV_READ | UEV_WRITE)
+#define UEV_EVENT_MASK  (UEV_READ | UEV_WRITE | UEV_PRI)
 
 /* Main libuEv context type */
 typedef struct {

uev.h

@@ -34,6 +34,7 @@
 #define UEV_NONE        0
 #define UEV_READ        EPOLLIN
 #define UEV_WRITE       EPOLLOUT
+#define UEV_PRI         EPOLLPRI
 
 /* Run flags */
 #define UEV_ONCE        1