`flare.runtime.reuseport`

SO_REUSEPORT helpers for thread-per-core listeners.

On Linux (kernel >= 3.9) and macOS, multiple listening sockets can bind to the same port when every listener has SO_REUSEPORT set; the kernel then round-robins incoming connections across the set of listeners. This is the shape a thread-per-core HTTP server wants: N workers, each with its own listener, the kernel doing fair dispatch.

flare.tcp.TcpListener already exposes bind_with_options; this module just gives the multicore scheduler a self-documenting function name (bind_reuseport) and a small sanity check over the returned listener's address.

Functions

`bind_reuseport`

def bind_reuseport(addr: SocketAddr, backlog: Int = Int(1024)) -> TcpListener

Bind a TcpListener with SO_REUSEPORT enabled.

Multiple workers can call bind_reuseport with the same addr and the kernel load-balances accepted connections across them by hashing the connection 4-tuple to one of the bound listeners.

.. note::

The 4-tuple hash distribution is uneven under bursty connection arrival: a 256-connection storm from a wrk2-style load generator can land 80+ conns on one listener and 30 on another. prefers the shared-listener path (bind_shared + Reactor.register_exclusive) for multi-worker servers because the kernel-driven exclusive wakeup gives a fairer accept-time distribution. bind_reuseport remains available for the multi-process load-balancing case across separate flare processes (where shared-fd inheritance is impossible) and for backward compatibility with benchmarks.

Args: addr: Local address to bind.; backlog: Listen backlog (default 1024 — higher than the single-worker 128 so a burst of SYNs is less likely to overflow before any worker picks them up).

Raises AddressInUse: If a previous bind did not set SO_REUSEPORT on the same port. NetworkError: For any other OS error.

`bind_shared`

def bind_shared(addr: SocketAddr, backlog: Int = Int(1024)) -> TcpListener

Bind a single TcpListener to be shared across workers.

The multi-worker Scheduler creates ONE listener via bind_shared, then hands its fd to every worker. Each worker registers the fd in its own Reactor with Reactor.register_exclusive, which sets EPOLLEXCLUSIVE on Linux (>= 4.5) so the kernel wakes only one worker per accept-event. On macOS / kqueue the flag is unavailable and the accept side falls back to non-blocking accept() returning EAGAIN for losers, so the wakeup pattern is "wake-all, one-wins" but practically still bounded by the single accept queue.

Compared to bind_reuseport, this avoids the 4-tuple-hash distribution variance that produces head-of-line tail latency on a busy worker — the kernel's exclusive wakeup naturally routes new accepts to whichever worker is currently waiting in epoll_wait.

Only one process can hold a bind_shared listener for a given port at a time. For cross-process load balancing (multiple flare processes on the same port), use bind_reuseport.

Args: addr: Local address to bind.; backlog: Listen backlog (default 1024). With EPOLLEXCLUSIVE the accept queue is shared across all workers so the backlog can be the same as the single-worker default without head-of-line risk.

Raises AddressInUse: If the port is already in use. NetworkError: For any other OS bind/listen error.