0.8.0
flare / tcp / listener

mod listener

src

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.

Functions

fn accept_fd Accept one connection on a borrowed listener fd.

Structs

struct TcpListener A TCP socket in the listening state.
Detail Documentation

Functions

fn accept_fd § 

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 Int32

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.

Returns

TcpStream

A connected TcpStream for the new client.

Raises

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

Structs

struct 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())

Methods

fn __init__ Wrap an already-bound, listening ``RawSocket``.
fn __del__
fn bind Bind a TCP listener to ``addr`` with default options.
fn bind_with_options Bind with explicit backlog and ``SO_REUSEPORT`` control.
fn accept Block until an incoming connection arrives and return it.
fn local_addr Return the local address the listener is bound to.
fn as_raw_fd Return the underlying file descriptor.
fn close Close the listening socket. Idempotent.

fn __init__ static § 

__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 var RawSocket

Open, listening socket (ownership transferred).
local SocketAddr

The address the socket was bound to.
self out Self
Returns
Self

fn __del__ § 

__del__(deinit self)
Args
self deinit Self

fn bind static § 

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 SocketAddr

The local address to bind (use port 0 for OS-assigned port).
Returns
Self

A TcpListener ready to call accept().
Raises

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

fn bind_with_options static § 

bind_with_options(addr: SocketAddr, backlog: 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 SocketAddr

The local address to bind.
backlog Int

Maximum length of the pending-connections queue.

Default: 128
reuse_port Bool

If True, set SO_REUSEPORT (useful for multi-process load balancing).

Default: False
Returns
Self

A TcpListener ready to call accept().
Raises

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

fn accept § 

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()
Args
self Self
Returns
TcpStream

A connected TcpStream for the new client.
Raises

NetworkError: If accept(2) fails.

fn local_addr § 

local_addr(self) -> SocketAddr

Return the local address the listener is bound to.

Args
self Self
Returns
SocketAddr

The bound SocketAddr (useful when port 0 was requested).

fn as_raw_fd § 

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.

Args
self Self
Returns
c_int

The kernel file descriptor for the listening socket.

fn close § 

close(mut self)

Close the listening socket. Idempotent.

Args
self mut Self