--- title: Use event ports for native event loops; keep the epoll emulation for Linux code area: api impact: HIGH tags: [event-ports, epoll, eventfd, timerfd, signalfd, kqueue, porting, event-loop] verified: 2026-11-04 --- # Use event ports for native event loops; keep the epoll emulation for Linux code Event ports (`port_create`, `port_associate`, `port_get`/`port_getn`) are the native illumos event API. illumos also ships Linux-compatible epoll, eventfd and timerfd, has signalfd, and has no kqueue. Pick wrong and you get a backend that does not build, close(2) races, or a loop that wakes itself forever. **Antipattern** ```c int kq = kqueue(); /* no kqueue on illumos (progress.md: entr needs sys/event.h, BSD-only): a kqueue-only backend does not build */ epoll_ctl(ep, EPOLL_CTL_ADD, fd, &ev); /* threads that close(2) watched fds: races epoll(7) calls "unresolvable", even with EPOLLONESHOT */ ev.events = EPOLLIN | EPOLLEXCLUSIVE; /* effectively a no-op on illumos; EPOLLWAKEUP and EPOLLMSG are ignored */ port_associate(port, PORT_SOURCE_FD, fd, POLLIN, ud); /* re-associated before the fd is drained: an event is sent at once, again and again (COSMIC: 3-4 GB clients) */ port_associate(port, PORT_SOURCE_FD, ep, POLLIN, ud); /* an epoll fd inside an event port: never wakes the port */ ``` **The Solnix way** ```sh grep -rnE 'kqueue|kevent|epoll_(create|ctl|wait)|eventfd|timerfd_create|signalfd|port_create' src/ # kqueue -> none: build the project's epoll or event-ports backend, or write an event-ports one # (Solnix's wayland build dropped its kqueue epoll-shim: "illumos has native epoll") # epoll_* -> is there, designed to be binary-compatible with Linux; check the code's #ifdef/cfg gates # name illumos (Solnix's wayland-backend patch added it), and audit threads that close fds # a new backend -> event ports: port_create, port_associate (one-shot), port_get/port_getn, port_send to wake # eventfd, timerfd, signalfd -> present; their fds work with poll(2), port_get(3C) and epoll_wait(3C) # eventfd_read/eventfd_write exist "for compatibility with glibc" # timerfd_create: CLOCK_REALTIME or CLOCK_HIGHRES (CLOCK_MONOTONIC is an alias for CLOCK_HIGHRES); # its ERRORS list EPERM for CLOCK_HIGHRES without {PRIV_PROC_CLOCK_HIGHRES}: test the unprivileged case # signalfd: block the signals first, or a handler may take them instead of read(2) # Rust: the polling crate uses event ports by default, which have no level-triggered mode; calloop on top of # it re-armed fds before dispatch, so Solnix's fixup 73c4cf7 switched polling to epoll on illumos elfdump -s ./myprog | grep -E 'port_(create|associate|getn?)|epoll_' # what the binary calls ``` Solnix ships the gate's libc (`pkgs.solnix.libc`, not glibc), so these are the illumos implementations, with illumos semantics (which library holds the epoll functions: see Unverified). rustix 1.1.4 exposes epoll on illumos; rustix 0.38 does not, so a crate on 0.38 has no epoll path there. **The illumos way** (OpenIndiana, OmniOS, SmartOS) ```c #include port = port_create(); /* a file descriptor; close(2) destroys the port */ error = port_associate(port, PORT_SOURCE_FD, fds[index], POLLIN, mypointer); error = port_get(port, &pev, &timeout); /* NULL timeout blocks; port_getn() fetches many */ fd = pev.portev_object; /* now dissociated: read it, then port_associate() it again */ port_send(port, 0, mypointer); /* a user-defined event, no fd needed (calloop wakes its loop this way) */ ``` The gate's libc provides these on every illumos distribution. Native alternatives: `timer_create(3C)` with `SIGEV_PORT` for timers, and `PORT_SOURCE_FILE` (`FILE_MODIFIED`, `FILE_DELETE`, ...) to watch files and directories. **The difference.** Same as illumos. epoll and timerfd exist to accommodate Linux-borne code (eventfd is Linux-borne too), and native code should prefer event ports. A `signalfd` used with epoll or an event port after fork(2) can be undefined unless the child only closes the descriptors. SmartOS can instead run an unported Linux binary in an LX zone, which maps its `epoll_create`; LX zones are not built yet on Solnix (handbook: LX zones, Honest status). **Check.** `elfdump -s ./myprog | grep -E 'port_(create|associate|getn?)|epoll_'` lists the event API the binary calls (run it on the shared library that owns the event loop, e.g. libuv.so, when there is one). `port_*` symbols and no `epoll_*` ones mean it uses event ports. For file watching (Linux inotify), the illumos source is `PORT_SOURCE_FILE`. **Unverified** - Which backend libevent and libuv choose on Solnix: no source here says. - Which library holds `epoll_*`, `eventfd`, `timerfd_*` and `signalfd`: their pages name no `-l` flag, and libc(3LIB) INTERFACES lists the `port_*` functions but not these. **Sources** - [docs/progress.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/progress.md) (solnix 5a8e5ce), "entr-5.6 : needs sys/event.h (kqueue, BSD-only)" - [timerfd_create(3C)](https://solnix.io/docs/man/timerfd_create.3c) (illumos, CDDL), ERRORS (EPERM, PRIV_PROC_CLOCK_HIGHRES) - [port_create(3C)](https://solnix.io/docs/man/port_create.3c) (illumos, CDDL), DESCRIPTION (source table, PORT_SOURCE_FD, close(2)) - [port_associate(3C)](https://solnix.io/docs/man/port_associate.3c) (illumos, CDDL), DESCRIPTION (event sent immediately, one event per association, PORT_SOURCE_FILE events); Example 1 - [port_get(3C)](https://solnix.io/docs/man/port_get.3c) (illumos, CDDL), SYNOPSIS; DESCRIPTION (NULL timeout, port_getn) - [port_send(3C)](https://solnix.io/docs/man/port_send.3c) (illumos, CDDL), SYNOPSIS; DESCRIPTION - [docs/milkv-cosmic-plan.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/milkv-cosmic-plan.md) (solnix 5a8e5ce), (2) event ports (port_send as calloop's wakeup; polling uses port_create/port_associate/port_getn) - [epoll(7)](https://solnix.io/docs/man/epoll.7) (illumos, CDDL), DESCRIPTION; NOTES (prefer event ports, close(2) races, kqueue, fork semantics) - [epoll_ctl(3C)](https://solnix.io/docs/man/epoll_ctl.3c) (illumos, CDDL), EPOLLEXCLUSIVE, EPOLLWAKEUP, EPOLLMSG, EPOLLONESHOT - [eventfd(3C)](https://solnix.io/docs/man/eventfd.3c) and [eventfd(7)](https://solnix.io/docs/man/eventfd.7) (illumos, CDDL), DESCRIPTION (poll/port_get/epoll_wait; glibc compatibility; Linux-borne) - [timerfd_create(3C)](https://solnix.io/docs/man/timerfd_create.3c) and [timerfd(7)](https://solnix.io/docs/man/timerfd.7) (illumos, CDDL), DESCRIPTION (clocks; SIGEV_PORT; Linux-borne applications) - [signalfd(3C)](https://solnix.io/docs/man/signalfd.3c) (illumos, CDDL), DESCRIPTION (blocked signals); NOTES (fork) - [libc(3LIB)](https://solnix.io/docs/man/libc.3lib) (illumos, CDDL), INTERFACES (port_create, port_associate, port_getn listed; no kqueue) - [elfdump(1)](https://solnix.io/docs/man/elfdump.1) (illumos, CDDL), -s - [docs/cosmic-illumos-integration-tests.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/cosmic-illumos-integration-tests.md) (solnix 5a8e5ce), §2 Event loops (polling backend and 73c4cf7; epoll fd nested in an event port; timerfd, eventfd) - [docs/cosmic-rust-stack.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/cosmic-rust-stack.md) (solnix 5a8e5ce), The wayland-backend illumos patch (rustix 1.1.4 exposes epoll on illumos; illumos added to the epoll cfg allowlist) - [docs/post-stable-backlog.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/post-stable-backlog.md) (solnix 5a8e5ce), PS-AARCH64-WAVE15 (wayland: kqueue epoll-shim dropped); "illumos has no epoll in rustix 0.38" - [handoff: from-builder-20261028T231241-cache7-hm-rows-request](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/from-builder-20261028T231241-cache7-hm-rows-request.md), not built: no illumos backend (inotify/kqueue) - [Handbook: How Solnix is built](https://solnix.io/docs/handbook/how-solnix-is-built#pkgssolnix--the-fine-grained-world) (site 307b67f), The illumos gate; `pkgs.solnix.*` — the fine-grained world (`pkgs.solnix.libc`) - [Handbook: LX-branded zones](https://solnix.io/docs/handbook/lx-zones#honest-status) (site 307b67f), What an LX-branded zone is; Honest status