Awesome
libkqueue
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
- vnode
- socket
- proc
- user
- timer
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:
-DENABLE_ASAN=YES
, enables address sansitizer (detects use after free issues, and out of bounds accesses).-DENABLE_LSAN=YES
, enables leak sanitizer (detects memory leaks).-DENABLE_TSAN=YES
, enables thread sanitizer (detects races).-DENABLE_UBSAN=YES
, enables undefined behaviour sanitizer (detects misaligned accesses, integer wrap, divide by zero etc...).
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:
-
NOTE_VERSION
return the current version as a 32bit unsigned integer in the formatMMmmpprr
(Major
,minor
,patch
,release
) in thedata
field of an entry in the eventlist. -
NOTE_VERSION_STR
return the current version as a string in theudata
field of an entry in the eventlist. -
NOTE_THREAD_SAFE
defaults to on (1
).- If the
data
field is0
the global mutex will not be locked after resolving a kqueue fd to a kqueue structure. The application must guarantee any given kqueue will be created and destroyed by the same thread. - If the
data
field is1
kqueues can be created and destroyed in different threads safely. This may add contention around the global mutex.
- If the
-
NOTE_FORK_CLEANUP
defaults to on (1
).- If the
data
field is0
no resources will be cleaned up on fork. - if the
data
field is1
all kqueues will be closed/freed on fork.
The default behaviour matches native kqueue but may be expensive if many kqueues are active. If
EV_RECEIPT
is set, the previous value of cleanup flag will be provided in a receipt event. - If the
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:
-
NOTE_DEBUG
defaults to off0
, but may be overridden by the environmental variableKQUEUE_DEBUG
.- If the
data
field is0
no debug messages will be produced. - If the
data
field is1
debug messages will be produced.
If
EV_RECEIPT
is set the previous value of debug flag will be provided in a receipt event. - If the
-
NOTE_DEBUG_PREFIX
defaults toKQ
. Logging prefix will be set to the value of a string pointed to by thedata
field. Logging prefix strings will be memdup'd. -
NOTE_DEBUG_FUNC
defaults to a function which writes debug information to stderr. Thedata
field should contain a pointer to a function with the signaturevoid (*debug_func)(char const *fmt, ...)
, orNULL
to restore to original logging function.
Building Applications
CFLAGS += -I/usr/include/kqueue
LDFLAGS += -lkqueue
Tutorials & Examples
Handling TCP Connections with Kqueue Event Notification
Releases History
See the ChangeLog.