Skip to content

Glossary

kqueue

BSD's I/O event notification mechanism — register interest in events from file descriptors, sockets, timers, processes, signals, and get woken when they fire.

kqueue(2) is BSD's I/O event notification mechanism — the equivalent of Linux's epoll. Originally from FreeBSD; XNU inherits it largely unchanged.

A kqueue is a file descriptor backed by an in-kernel queue of events. You register interest in specific events via kevent(2):

int kq = kqueue();
struct kevent ev;
EV_SET(&ev, fd, EVFILT_READ, EV_ADD, 0, 0, NULL);
kevent(kq, &ev, 1, NULL, 0, NULL);   // register

struct kevent events[16];
int n = kevent(kq, NULL, 0, events, 16, NULL);   // block until events arrive

Event sources kqueue knows about:

  • EVFILT_READ / EVFILT_WRITE — file descriptors ready for I/O.
  • EVFILT_VNODE — vnode changes (file written, renamed, deleted).
  • EVFILT_PROC — process state changes (exit, fork).
  • EVFILT_SIGNAL — signal received.
  • EVFILT_TIMER — periodic or one-shot timer.
  • EVFILT_MACHPORT — Mach port has a message.
  • EVFILT_USER — user-triggered event for cross-thread wake.
apple-oss-distributions/xnubsd/kern/kern_event.ckqueue implementation — the kernel side of every kevent registration.View on GitHub(line —)

kqueue is the foundation libdispatch (GCD) is built on. Every GCD DispatchSource is a kqueue registration under the hood; the dispatch worker threads block in kevent waiting for any registered source to fire.

See also: BSD, and the BSD personality article.