Crate kevy_sys 

kevy-sys — kevy’s network-boundary layer.

One of kevy’s three OS-boundary crates (alongside the publishable kevy-uring and kevy-madvise). This is the server-internal piece — hand-curated to the exact subset of sockets and the readiness poller (kqueue on macOS, epoll on Linux) that kevy’s server needs. Every binding is declared by hand with unsafe extern "C" (no libc crate, no third-party dep). On Linux these symbols resolve through glibc, on macOS through libSystem — both already linked by std, so we add zero dependencies.

The poller here is readiness-based. The completion-based io_uring engine has moved to its own crate, kevy-uring; either can back the reactor on top (kevy-net), which exposes only a byte-level service contract.

Part of the kevy key–value server; not a generic OS-binding library.

Safety

unsafe is confined to the private ffi module’s extern "C" declarations and the thin wrappers that call them. The bindings match the platform libc ABI (socklen_t = u32; struct sockaddr_in, kevent, and epoll_event laid out per-OS/arch). All raw fds are owned by RAII types (Socket, Poller, Waker) that close on drop, and errors are read via std::io::Error::last_os_error(). The public API is safe.

Example

use kevy_sys::{Poller, tcp_listen};

let listener = tcp_listen([127, 0, 0, 1], 6379, 1024)?;
listener.set_nonblocking()?;

let poller = Poller::new()?;
poller.add(listener.raw(), /* read */ true, /* write */ false)?;

let mut events = Vec::new();
poller.wait(&mut events, Some(1000))?; // block up to 1s
for ev in &events {
    if ev.fd == listener.raw() && ev.readable {
        let conn = listener.accept()?;
        conn.set_nodelay()?;
        // ... read/write `conn` ...
    }
}

Structs

Event

A readiness notification for one file descriptor.

Poller

Socket

An owned socket file descriptor. Closes itself on drop via our own close.

Waker

A self-pipe used to wake a Poller blocked in wait from another thread. Register read_fd() in the poller for read-readiness; call wake() from any thread to make the poll return; call drain() when the read end fires.

Constants

SIGINT

v1.39 — SIGINT constant (Ctrl-C).

SIGTERM

v1.39 — SIGTERM constant.

SIGXFSZ

v1.58 — SIGXFSZ constant (write would exceed RLIMIT_FSIZE). Default action is Core — installing a handler prevents the kernel from dumping core and lets kevy exit gracefully on disk-full / fsize-limit conditions.

Functions

install_signal_handler

v1.39 — install a C-style handler for signum. Safe wrapper around signal(2); the handler must be async-signal-safe (no allocator, no syscall beyond a tiny set). Typical use: handler stores into a static AtomicBool which the main loop polls.

tcp_listen

Create a blocking IPv4 TCP listener bound to ip:port with SO_REUSEADDR. Pass port == 0 to let the OS assign an ephemeral port.

tcp_listen_reuseport

Like tcp_listen but also sets SO_REUSEPORT, so multiple listeners can share one port (one per thread-per-core shard).

unix_listen

Create a blocking AF_UNIX stream listener bound to path. Unlinks any existing file at the path first (mirroring valkey/redis’s unixsocket option). UDS bypasses the TCP stack — useful when client+server are on the same host and the TCP loopback round-trip is the bench-shape floor.

waker

Create a non-blocking self-pipe waker.