Module

net.listener

Network listener — creates and configures server sockets.

Binds to the configured address, sets socket options (SO_REUSEADDR, SO_REUSEPORT if available), and returns ready-to-accept sockets.

Phase 2 multi-worker strategy:

  • SO_REUSEPORT available (Linux): each worker gets its own independently bound socket — the kernel distributes connections across them.
  • SO_REUSEPORT unavailable (macOS, Windows): one socket is created and shared by all workers — all workers accept from the same fd.

The worker receives a socket and does not know which strategy was used.

6Functions

Functions

create_listener 1 socket.socket ▼
Create and bind a single server socket from configuration. If ``config.uds`` i…
def create_listener(config: ServerConfig) -> socket.socket

Create and bind a single server socket from configuration.

Ifconfig.udsis set, creates a Unix domain socket. Otherwise creates a TCP socket bound toconfig.host:config.port.

Parameters
Name Type Description
config ServerConfig

Server configuration with host, port, and backlog settings.
Returns
socket.socket
create_listeners 2 list[socket.socket] ▼
Create server sockets for *count* workers. On platforms with ``SO_REUSEPORT`` …
def create_listeners(config: ServerConfig, count: int) -> list[socket.socket]

Create server sockets for count workers.

On platforms withSO_REUSEPORTeach worker gets its own independently bound socket so the kernel distributes connections. WhenSO_REUSEPORTis unavailable, a single socket is created and the same object is returned for every worker (shared-fd strategy).

Parameters
Name Type Description
config ServerConfig

Server configuration.
count int

Number of worker sockets needed.
Returns
list[socket.socket]
has_so_reuseport 0 bool ▼
Check if SO_REUSEPORT is available on this platform.
def has_so_reuseport() -> bool
Returns
bool
_bind_unix_socket 1 socket.socket ▼
Create, bind, and listen on a Unix domain socket. Removes any stale socket fil…
def _bind_unix_socket(config: ServerConfig) -> socket.socket

Create, bind, and listen on a Unix domain socket.

Removes any stale socket file before binding. The socket file should be cleaned up on shutdown viacleanup_unix_socket().

Parameters
Name Type Description
config ServerConfig
Returns
socket.socket
cleanup_unix_socket 1 None ▼
Remove the Unix domain socket file on shutdown. Safe to call even if no UDS is…
def cleanup_unix_socket(config: ServerConfig) -> None

Remove the Unix domain socket file on shutdown.

Safe to call even if no UDS is configured (no-op).

Parameters
Name Type Description
config ServerConfig
_bind_socket 1 socket.socket ▼
Create, configure, bind, and listen on a single TCP socket. Uses ``getaddrinfo…
def _bind_socket(config: ServerConfig) -> socket.socket

Create, configure, bind, and listen on a single TCP socket.

Usesgetaddrinfoto resolve the host, supporting both IPv4 and IPv6 addresses. When binding to an IPv6 address, enables dual-stack (IPV6_V6ONLY=False) where possible so both IPv4 and IPv6 clients can connect.

Parameters
Name Type Description
config ServerConfig
Returns
socket.socket