Module: net.tcp

Source: ./net/tcp.reef

Overview

net.tcp - TCP socket operations

Provides TCP client and server functionality with IPv4/IPv6 support, connection timeouts, and socket options (nodelay, keepalive).

The 10 fallible ops (connect/connect_timeout/listen/accept, send/send_all/ send_bytes, recv/recv_bytes/recv_all) return result.Result[T, error.Error]. Failures are classified via net.socket's net_err() (errno -> ErrorKind, with a strerror() message), except tcp_connect_timeout's -2 timeout sentinel which maps to Err(ErrorKind_Timeout()) directly (errno may not be set for a timeout).

recv/recv_all treat a clean close/EOF as Ok(""), NOT an error: the runtime returns 0 (recv) or -3 (recv_all) for a graceful close, which is a normal end-of-stream condition, not a failure. Only a negative (non-close) return from the runtime becomes Err(net_err()).

recv_bytes keeps its out-param buffer (byte arrays aren't returned by value): Ok(n) for n >= 0 (0 = clean close, still Ok), Err(net_err()) for n < 0.

Connection management (close/shutdown*), socket options (set_nodelay/ set_keepalive/set_timeout), and peer/local accessors are unchanged -- they don't fail in ways worth modeling as Result (close/shutdown races are inherently best-effort; accessors have no failure mode callers act on).

Functions

fn tcp_connect(host: string, port: int): result.Result[int, error.Error]

Connect to a TCP server Ok(socket fd) on success, Err(socket.net_err()) on failure.

fn tcp_connect_timeout(host: string, port: int, timeout_ms: int): result.Result[int, error.Error]

Connect with timeout Ok(socket fd) on success. The runtime's -2 timeout sentinel maps to Err(ErrorKind_Timeout()) BEFORE consulting net_err() (errno may not be set for a timeout); any other negative fd maps to Err(socket.net_err()).

fn tcp_listen(port: int, backlog: int): result.Result[int, error.Error]

Create a listening server socket Ok(server socket fd) on success, Err(socket.net_err()) on failure.

fn tcp_accept(server_fd: int): result.Result[int, error.Error]

Accept an incoming connection Ok(client socket fd) on success, Err(socket.net_err()) on failure. Call tcp_peer_addr() and tcp_peer_port() after to get client info

fn tcp_send(sockfd: int, data: string): result.Result[int, error.Error]

Send string data Ok(number of bytes sent) on success, Err(socket.net_err()) on failure.

fn tcp_send_all(sockfd: int, data: string): result.Result[int, error.Error]

Send all string data, retrying as needed Ok(number of bytes sent) (should equal string length) on success, Err(socket.net_err()) on failure.

fn tcp_send_bytes(sockfd: int, data: [uint8], len: int): result.Result[int, error.Error]

Send byte array Ok(number of bytes sent) on success, Err(socket.net_err()) on failure.

fn tcp_recv(sockfd: int, max_len: int): result.Result[string, error.Error]

Receive data as string Ok(received string, GC-copied; may be shorter than max_len) on success; Ok("") on clean close/EOF (runtime returns 0 -- NOT an error); Err(socket.net_err()) on failure (runtime returns < 0).

fn tcp_recv_bytes(sockfd: int, buffer: [uint8], max_len: int): result.Result[int, error.Error]

Receive data into byte array (out-param buffer kept -- byte arrays aren't returned by value) Ok(number of bytes received) on success (0 = clean close, still Ok); Err(socket.net_err()) on failure (runtime returns < 0).

fn tcp_recv_all(sockfd: int, len: int): result.Result[string, error.Error]

Receive exactly len bytes Ok(received string, GC-copied) on success; Ok("") on clean close before all data received (runtime returns -3) or a zero-length request (runtime returns 0) -- NOT an error; Err(socket.net_err()) on failure (runtime returns -1).

fn tcp_close(sockfd: int): int

Close socket

fn tcp_shutdown(sockfd: int, how: int): int

Shutdown socket how: 0=read, 1=write, 2=both

fn tcp_shutdown_read(sockfd: int): int

Convenience shutdown functions

fn tcp_shutdown_write(sockfd: int): int

fn tcp_shutdown_both(sockfd: int): int

fn tcp_set_nodelay(sockfd: int, enable: bool): int

Enable/disable Nagle's algorithm (TCP_NODELAY) Disabling (enable=true) reduces latency for small packets

fn tcp_set_keepalive(sockfd: int, enable: bool): int

Enable/disable TCP keepalive

fn tcp_set_timeout(sockfd: int, recv_ms: int, send_ms: int): int

Set send/receive timeouts in milliseconds 0 = no timeout

fn tcp_peer_addr(): string

Get peer address (call after accept or connect)

fn tcp_peer_port(): int

Get peer port (call after accept or connect)

fn tcp_local_port(sockfd: int): int

Get local port of bound socket

Generated by reefc doc