Kqueue is a scalable event notification interface introduced in FreeBSD 4.1 in July 2000, also supported in NetBSD, OpenBSD, DragonFly BSD, and macOS. Kqueue was originally authored in 2000 by Jonathan Lemon, then involved with the FreeBSD Core Team. Kqueue makes it possible for software like nginx to solve the c10k problem.
Kqueue provides efficient input and output event pipelines between the kernel and userland. Thus, it is possible to modify event filters as well as receive pending events while using only a single system call to
kevent(2) per main event loop iteration. This contrasts with older traditional polling system calls such as
select(2) which are less efficient, especially when polling for events on numerous file descriptors.
Kqueue not only handles file descriptor events but is also used for various other notifications such as file modification monitoring, signals, asynchronous I/O events (AIO), child process state change monitoring, and timers which support nanosecond resolution, furthermore kqueue provides a way to use user-defined events in addition to the ones provided by the kernel.
Some other operating systems which traditionally only supported
poll(2) also currently provide more efficient polling alternatives, such as epoll on Linux and I/O completion ports on Windows and Solaris.
The function prototypes and types are found in
Creates a new kernel event queue and returns a descriptor.
int kevent(int kq, const struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, const struct timespec *timeout);
Used to register events with the queue, then wait for and return any pending events to the user. In contrast to epoll, kqueue uses the same function to register and wait for events, and multiple event sources may be registered and modified using a single call. The
changelist array can be used to pass modifications (changing the type of events to wait for, register new event sources, etc.) to the event queue, which are applied before waiting for events begins.
nevents is the size of the user supplied
eventlist array that is used to receive events from the event queue.
EV_SET(kev, ident, filter, flags, fflags, data, udata);
A macro that is used for convenient initialization of a
struct kevent object.
OS-independent libraries with support for kqueue:
Kqueue equivalent for other platforms:
- on Solaris, Windows and AIX: I/O completion ports. Note that completion ports notify when a requested operation has completed, whereas
kqueuecan also notify when a file descriptor is ready to perform an I/O operation.
- on Linux:
- Jonathan Lemon (2000). "kqueue, kevent — kernel event notification mechanism". BSD Cross Reference. FreeBSD, OpenBSD, NetBSD, DragonFly BSD.
- Jonathan Lemon (2001-05-01). Kqueue: A generic and scalable event notification facility (PDF). Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference. USENIX (published June 25–30, 2001).
- "Connection processing methods". nginx.org.
- Andrew Alexeev (2012). "§14. nginx". In Amy Brown; Greg Wilson (eds.). The Architecture of Open Source Applications, Volume II: Structure, Scale and a Few More Fearless Hacks. Lulu.com. ISBN 9781105571817.
- libkqueue on GitHub
- FreeBSD System Calls Manual –
- FreeBSD System Calls Manual –
- libbrb_core implements an abstraction for an event-oriented base, using
- FreeBSD source code of the
- OpenBSD source code of the
- NetBSD source code of the
- DragonFly BSD source code of the