`flare.tcp.listener`

TCP listener: a socket bound and listening for incoming connections.

TcpListener wraps a RawSocket in the listening state. Call accept() to receive incoming connections as TcpStream instances.

Design rules enforced here:

SO_REUSEADDR is set before every bind() call.
TCP_NODELAY is set on every accepted TcpStream.
accept() sets TCP_NODELAY on the client socket automatically.

Structs

`TcpListener`

struct TcpListener

A TCP socket in the listening state.

TcpListener accepts incoming TCP connections and returns each one as a TcpStream. SO_REUSEADDR is always set before bind().

The listener is closed automatically when the struct is destroyed.

Thread safety: Not thread-safe . Do not call accept() concurrently.

Example:

from flare.tcp import TcpListener, TcpStream
from flare.net import SocketAddr

var listener = TcpListener.bind(SocketAddr.localhost(8080))
var stream = listener.accept() # blocks until a client connects
stream.write_all("welcome".as_bytes())

Implements Movable

`init`

def __init__(out self, var socket: RawSocket, local: SocketAddr)

Wrap an already-bound, listening RawSocket.

Safety: socket must already be in the listening state (listen(2) was called). The caller must not close socket after this.

Args: socket: Open, listening socket (ownership transferred).; local: The address the socket was bound to.

`deinit`

def __deinit__(deinit self)

`bind`

def bind(addr: SocketAddr) -> Self

Bind a TCP listener to addr with default options.

SO_REUSEADDR is set before binding. The backlog is 128.

Example:

var l = TcpListener.bind(SocketAddr.localhost(8080))

Args: addr: The local address to bind (use port 0 for OS-assigned port).

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

`bind_with_options`

def bind_with_options(addr: SocketAddr, backlog: Int = Int(128), reuse_port: Bool = False) -> Self

Bind with explicit backlog and SO_REUSEPORT control.

Example:

var l = TcpListener.bind_with_options(
    SocketAddr.localhost(8080), backlog=1024, reuse_port=True
)

Args: addr: The local address to bind.; backlog: Maximum length of the pending-connections queue.; reuse_port: If True, set SO_REUSEPORT (useful for multi-process load balancing).

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

`accept`

def accept(self) -> TcpStream

Block until an incoming connection arrives and return it.

Sets TCP_NODELAY on the accepted socket automatically.

Example:

while True:
    var client = listener.accept()
    client.write_all("hello".as_bytes())
    client.close()

Raises NetworkError: If accept(2) fails. If the peer address cannot be decoded afterwards the accepted socket is closed before the error propagates (it is never leaked).

`local_addr`

def local_addr(self) -> SocketAddr

Return the local address the listener is bound to.

`as_raw_fd`

def as_raw_fd(self) -> c_int

Return the underlying file descriptor.

Intended for the shared-listener scheduler: bind once on the main thread, then hand the fd (a small integer) to every worker via the per-worker context struct. Workers call flare.tcp.accept_fd directly rather than touching the non-thread-safe TcpListener object.

The returned fd is borrowed; its lifetime is tied to self. Callers must not close(fd) themselves; let TcpListener own the close.

`close`

def close(mut self)

Close the listening socket. Idempotent.

Functions

`accept_fd`

def accept_fd(listener_fd: Int32) -> TcpStream

Accept one connection on a borrowed listener fd.

Functionally equivalent to TcpListener.accept(self) but takes the listener as a raw integer fd, so the caller can share a single listener across multiple workers without giving any one worker ownership of the underlying TcpListener (multi-worker scheduler path; see flare.runtime.scheduler).

The returned TcpStream owns the accepted client fd and has TCP_NODELAY already set, matching TcpListener.accept's contract. Same error semantics: raises NetworkError on accept(2) failure (including EAGAIN / EWOULDBLOCK, which the multi-worker reactor catches as a normal "no more pending conns" signal).

Args: listener_fd: Fd of a listener socket. Caller must keep the socket open for the duration of this call; this function does NOT take ownership of the fd.

Raises NetworkError: If accept(2) fails. The errno-bearing variant lets the caller distinguish EAGAIN (drain the accept loop) from a hard failure.