Home

Awesome

libkqueue

CI Linux CI Windows Test suite FreeBSD Test suite macOS Coverity

A user space implementation of the kqueue(2) kernel event notification mechanism libkqueue acts as a translator between the kevent structure and the native kernel facilities on Linux, Android, Solaris, and Windows.

libkqueue is not perfect, and you may need to change the behaviour of your application to work around limitations on a given platform. Please see BUGS for known behavioural differences between libkqueue and BSD kqueues.

Supported Event Types

Installation - Linux, Solaris

cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib <path to source>
make
make install

Installation - Red Hat

cmake3 -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib <path to source>
make
cpack3 -G RPM

Installation - Debian

cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib <path to source>
make
cpack -G DEB

Installation - Android

cmake -G "Unix Makefiles" -DCMAKE_C_COMPILER=<path to NDK compiler> -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib <path to source>
make

Windows (Visual Studio Project)

cmake -G "Visual Studio 14 2015" <path to source>
cmake --build .

Windows (clang/C2) (Visual Studio Project)

cmake -G "Visual Studio 14 2015" -T "LLVM-vs2014" <path to source>
cmake --build .

Windows (cross-compiling on Ubuntu using MinGW)

sudo apt-get install mingw-w64
rm -rf CMakeCache.txt CMakeFiles
mkdir build
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=Toolchain-mingw32.cmake ..
make

Xcode (project)

cmake -G "Xcode" <path to source>

Source archive

mkdir -p cmake-build-source
cd cmake-build-source
cmake ..
make package_source

Running Unit Tests

cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib -DENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Debug <path to source>
make
make test

Build & Running only the test suite

Helpful to see the behavior of the tests on systems with native kqueue, e.g: macOS, FreeBSD

cd test
cmake .
make
./libkqueue-test

To enable tests which expose bugs in native kqueue implementations pass -DWITH_NATIVE_KQUEUE_BUGS=1 to cmake. i.e. cmake . test/CMakeLists.txt -DWITH_NATIVE_KQUEUE_BUGS=1.

Debugging

For best results add -DCMAKE_BUILD_TYPE=Debug to your cmake invocation, this will disable optimisation and add debugging symbols to ensure your debugger produces usable output, it also enables asserts.

The environmental variable KQUEUE_DEBUG can then be set to enable debug output from libkqueue and the test utility.

KQUEUE_DEBUG=1 <your application>

When building under clang and some later versions of GCC, you can add the following flags:

libkqueue filter

The libkqueue filter EVFILT_LIBKQUEUE exposes runtime configuration options and data. When querying/configuring libkqueue using EVFILT_LIBKQUEUE the flags field should be set to EV_ADD, and the fflags field should be one of the following:

Example - retrieving version string:

struct kevent kev, receipt;

EV_SET(&kev, 0, EVFILT_LIBKQUEUE, EV_ADD, NOTE_VERSION_STR, 0, NULL);
if (kevent(kqfd, &kev, 1, &receipt, 1, &(struct timespec){}) != 1) {
    //error
}
printf("libkqueue version - %s", (char *)receipt.udata);

The following are only available in debugging builds of libkqueue:

Building Applications

CFLAGS += -I/usr/include/kqueue
LDFLAGS += -lkqueue

Tutorials & Examples

Kqueues for Fun and Profit

Handling TCP Connections with Kqueue Event Notification

Releases History

See the ChangeLog.