Udp
UDP datagram sockets, built for packet rate.
Every send and receive moves a BATCH of datagrams per kernel crossing: on Linux recvmmsg/sendmmsg plus UDP GSO (up to 64 equal-sized datagrams per transit) and opt-in GRO; elsewhere a nonblocking drain loop. Waits park the green thread, never an OS thread, so one scheduler thread can serve many sockets. For more than one core's worth of packets, open open_sharded sockets (SO_REUSEPORT) and give each its own task.
"Reliable" here means the socket layer never loses data on its own: sends wait for buffer space instead of dropping, and stats reports the datagrams the KERNEL dropped for lack of receive-buffer room, so a receiver that falls behind knows it. UDP itself still delivers each datagram at most once, in any order, or not at all.
Packets are binary-safe Strings. An UdpAddr is an opaque, comparable address value: get one from resolve, local_addr or a received datagram.
Public API: Udp.open(host, port) : Result(UdpSocket, UdpError) Udp.open_with(host, port, opts) : Result(UdpSocket, UdpError) Udp.open_sharded(host, port, n, opts) : Result(List(UdpSocket), UdpError) Udp.defaults() : UdpOptions Udp.resolve(host, port) : Result(UdpAddr, UdpError) Udp.connect(sock, addr) : Result((), UdpError) Udp.send_to(sock, addr, data) : Result((), UdpError) Udp.send(sock, data) : Result((), UdpError) Udp.send_batch(sock, addr, payloads) : Result(Int, UdpError) Udp.send_batch_connected(sock, payloads) : Result(Int, UdpError) Udp.send_many(sock, [(addr, data)]) : Result(Int, UdpError) Udp.recv(sock, max_size, timeout_ms) : Result(Option((UdpAddr, String)), UdpError) Udp.recv_batch(sock, max_msgs, max_size, ms) : Result(List((UdpAddr, String)), UdpError) Udp.local_addr(sock) / Udp.local_port(sock) Udp.addr_to_string(addr) / Udp.addr_port(addr) Udp.stats(sock) : UdpStats Udp.close(sock) : () Udp.error_message(e) : String
Types
UdpSocket options for open_with.
reuse_addr,reuse_port: SO_REUSEADDR / SO_REUSEPORT.reuse_port
lets several sockets bind one port; Linux spreads flows across them.broadcast: allow sending to a broadcast address.gso: batch equal-sized sends into one kernel transit (Linux; turned
off automatically if the kernel or NIC refuses it).gro: let the kernel coalesce a flow's received datagrams (Linux).
Datagrams still come back one by one; fewer syscalls deliver them.recv_buffer,send_buffer: requested socket buffer bytes (0 keeps
the OS default). Linux caps them at net.core.rmem_max / wmem_max unless
the process has CAP_NET_ADMIN; raise those sysctls for real receive
headroom, since a full receive buffer is where UDP loses packets.Counters for a socket. rx_dropped is the kernel's count of datagrams dropped because the receive buffer was full, as of the last receive (Linux; -1 where the platform does not report it). tx_stalls counts the times a send had to wait for buffer space instead of dropping.
Functions
Render an address: "127.0.0.1:9000", "[::1]:9000".
Fix the socket's peer. send and send_batch_connected then need no address, the kernel skips a route lookup per datagram, only that peer's datagrams are received, and an ICMP "port unreachable" surfaces as an error on a later call instead of vanishing.
The defaults open uses: GSO on, GRO off, 8 MiB receive and send buffers requested, no address reuse.
Examples
Udp.open_with("0.0.0.0", 9000, { Udp.defaults() with reuse_port: true })A human-readable description of a UdpError.
Examples
Udp.error_message(SendFailed("boom")) -- "send failed: boom"The address this socket is bound to.
The port this socket is bound to (the one the OS picked for port 0).
Bind a UDP socket with defaults(). host "" or "0.0.0.0" is every IPv4 interface, "::" every interface over IPv4 and IPv6; port 0 picks a free port (see local_port).
Examples
let? sock = Udp.open("127.0.0.1", 0)Open n sockets on one port with SO_REUSEPORT, one per receiving task. Linux hashes each flow to one socket, so n tasks each draining their own socket scale across cores. Port 0 picks a free port for the first and binds the rest to it. On failure every socket opened so far is closed.
Examples
let? socks = Udp.open_sharded("0.0.0.0", 9000, 4, Udp.defaults())Bind a UDP socket with explicit options.
Examples
Udp.open_with("::", 5353, { Udp.defaults() with reuse_addr: true })Receive one datagram; Ok(None) if none arrives within timeout_ms. Prefer recv_batch for volume.
Receive up to max_msgs datagrams, in arrival order, each as (from, payload). Whatever is already queued comes back at once; otherwise the task parks until data arrives or timeout_ms passes (0: do not wait; negative: wait for ever). A timeout is Ok([]). A payload longer than max_size is truncated to it; 65535 never truncates.
Examples
match Udp.recv_batch(sock, 256, 2048, 100) do
Ok(dgrams) -> List.map(dgrams, handle)
Err(e) -> println(Udp.error_message(e))
endLook up host and pair it with port. IPv4 is preferred when the host has both, so the address works from an IPv4 socket. Resolve once and reuse the UdpAddr: sends take it without another lookup.
Examples
let? dst = Udp.resolve("127.0.0.1", 9000)Send one datagram to the connected peer.
Send every payload to a, in order, as one batch: the fast path. Waits for buffer space rather than dropping. Ok(n) once all n are sent; a hard failure (e.g. a payload over 65507 bytes) is Err(SendFailed(msg)) naming how many went out first.
Examples
let? n = Udp.send_batch(sock, dst, List.map(seqs, encode))send_batch to the connected peer (see connect).
Send a batch with a destination per datagram. Consecutive datagrams to one destination still share a kernel transit.
Send one datagram to a. Prefer send_batch for volume.