# listener

URL: /pounce/api/net/listener/
Section: net
Description: 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.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/net/listener/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fnet%2Flistener%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fnet%2Flistener%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fnet%2Flistener%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Fnet%2Flistener%2Findex.txt)

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.

9Functions

## 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.

If`config.uds`is set, creates a Unix domain socket.
Otherwise creates a TCP socket bound to`config.host:config.port`.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

Server configuration with host, port, and backlog settings.

##### Returns

`socket.socket`

`create_listeners`

3

`list[socket.socket]`

▼

Create server sockets for *count* workers.

When *shared* is True (recommended …

`def create_listeners(config: ServerConfig, count: int, *, shared: bool = False) -> list[socket.socket]`

Create server sockets for count workers.

When shared is True (recommended for thread workers), a single socket
is created and returned for every worker — all threads call`accept()`
on the same fd and the kernel distributes connections naturally.

When shared is False (required for process workers), each worker gets
its own independently bound`SO_REUSEPORT`socket on platforms that
support it. On platforms without`SO_REUSEPORT`the shared strategy
is used as a fallback regardless of this flag.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

Server configuration.

`count`
`int`

Number of worker sockets needed.

`shared`
`bool`

If True, all workers share a single socket fd. Use this for thread-based workers to avoid macOS SO_REUSEPORT distribution issues.

Default:`False`

##### Returns

`list[socket.socket]`

`create_udp_listener`

1

`socket.socket`

▼

Create and bind a single UDP socket for HTTP/3 (QUIC).

Binds to config.host:co…

`def create_udp_listener(config: ServerConfig) -> socket.socket`

Create and bind a single UDP socket for HTTP/3 (QUIC).

Binds to config.host:config.port. When config.port is 0 (ephemeral),
the OS assigns a port; callers must pass the resolved TCP port (from
the bound TCP socket) so HTTP/3 shares the advertised address.

UDP has no listen() or backlog.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

Server configuration with host and port.

##### Returns

`socket.socket`

`create_udp_listeners`

2

`list[socket.socket]`

▼

Create UDP sockets for *count* HTTP/3 workers.

Mirrors create_listeners: SO_RE…

`def create_udp_listeners(config: ServerConfig, count: int) -> list[socket.socket]`

Create UDP sockets for count HTTP/3 workers.

Mirrors create_listeners: SO_REUSEPORT for independent sockets,
shared socket when unavailable.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/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 via `cleanup_unix_socket()` (/pounce/api/net/listener/#cleanup_unix_socket).

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/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 (/pounce/api/config/#ServerConfig)`

`_bind_socket`

3

`socket.socket`

▼

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

Uses ``getaddrinfo…

`def _bind_socket(config: ServerConfig, *, _log_listen: bool = True, use_reuseport: bool = False) -> socket.socket`

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

Uses`getaddrinfo`to 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.

When`use_reuseport`is False (default for single-worker dev), a
second instance binding to the same address will fail with EADDRINUSE,
ensuring single-instance semantics for development.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

`_log_listen`
`bool`

Default:`True`

`use_reuseport`
`bool`

Default:`False`

##### Returns

`socket.socket`

`_bind_udp_socket`

3

`socket.socket`

▼

Create, configure, and bind a single UDP socket for HTTP/3.

UDP has no listen(…

`def _bind_udp_socket(config: ServerConfig, *, _log_bind: bool = True, use_reuseport: bool = False) -> socket.socket`

Create, configure, and bind a single UDP socket for HTTP/3.

UDP has no listen() or backlog. Uses same address resolution as TCP.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

`_log_bind`
`bool`

Default:`True`

`use_reuseport`
`bool`

Default:`False`

##### Returns

`socket.socket`