Tcp

Render the listener without exposing its host handle.

The port this listener is bound to. After Tcp.listen!(host, 0, …) this is the port the operating system chose. Closed after [close!].

Wait for a client to connect.

accept_timeout bounds this call only: NoTimeout waits indefinitely, and After(duration) gives up with Err(TcpErr(TimedOut)), after which the listener can accept again. io_timeout is the timeout the new Connection holds for its reads and writes; a connection never inherits the accept wait.

Closed after [close!].

match listener.accept!({ accept_timeout: After(Duration.seconds(1)), io_timeout: Duration.seconds(30) }) {
    Ok(conn) => serve!(conn)?
    Err(TcpErr(TimedOut)) => {}
    Err(Closed) => { return Ok({}) }
    Err(TcpErr(err)) => { return Err(TcpErr(err)) }
}

Stop listening and release the port. Closing again succeeds. Connections already accepted stay open.

Render the connection without exposing its host handle.

The same connection with another I/O timeout. Each read or write through the result is bounded as a whole by timeout.

# Poll: is a line already here?
match conn.with_timeout(Duration.millis(10)).read_line!() {
    Ok(line) => handle!(line)?
    Err(TcpErr(TimedOut)) => {}
    Err(err) => { return Err(err) }
}

The same connection with another limit, in bytes, on one record read by [read_until!], [read_line!] or Connection.lines. The delimiter or line terminator counts towards the limit. The default is 1,048,576 (1 MiB).

Read at most max_bytes bytes, returning as soon as any have arrived. Short reads are valid. Asking for zero bytes returns Ok([]) without waiting; otherwise the result is never empty, and a closed peer is Err(EndOfInput).

Read exactly count bytes. Zero succeeds without waiting.

If the peer closes before count bytes arrive the result is Err(UnexpectedEndOfInput). The bytes that did arrive are not consumed: [read_up_to!] returns them.

Read bytes through and including the next delimiter.

If the peer closes first, the bytes before the end are returned without a delimiter, and the read after that is Err(EndOfInput). So the result is never empty, and its last byte shows whether the delimiter arrived.

A record longer than the connection's line limit is Err(ReadLimitExceeded(limit)). The rest of that record, through its delimiter, is then discarded before the next read returns, as part of that read and within its timeout.

field = conn.read_until!('|')?

Read a line of text.

A line ends at \n. The terminator is not returned, and one \r before it is removed. If the peer closes without a final \n the last line is still returned; after that the result is Err(EndOfInput). An empty line is Ok("").

A line longer than the connection's line limit is Err(ReadLimitExceeded(limit)), and a line that is not valid UTF-8 is BadUtf8. Either way that line is skipped and the next call reads the line after it. For the bytes of a line, use conn.read_until!('\n').

Write all of bytes. They are sent at once, not buffered.

Write a string as UTF-8. It is sent at once, not buffered.

Lazily read this connection as non-empty chunks of at most 64 KiB, each returned as soon as it arrives. Chunk boundaries do not correspond to the peer's writes, records, or text encoding boundaries. For a chosen size, call [read_up_to!] in a loop.

Building the stream reads nothing; each item is one read with the connection's timeout. The stream ends when the peer closes. A TcpErr item, including TcpErr(TimedOut), is the last one; the connection stays usable and a new stream may be started.

for! item in conn.chunks() {
    bytes = item?
    $total = $total + bytes.len()
}

The stream holds no data of its own, so it can be mixed with the other reads and with writes. It keeps the connection open until it has finished or is released.

Lazily read this connection a line at a time, as [read_line!] does.

Building the stream reads nothing; each item is one read with the connection's timeout and line limit. The stream ends when the peer closes. BadUtf8 and ReadLimitExceeded items concern one line, and the stream continues with the next. A TcpErr item, including TcpErr(TimedOut), is the last one; the connection stays usable, so a client that tolerates idle periods calls conn.lines() again.

for! item in conn.lines() {
    match item {
        Ok(line) => Stdout.line!(line)?
        Err(BadUtf8(_)) => {}
        Err(ReadLimitExceeded(_)) => {}
        Err(TcpErr(err)) => { return Err(TcpErr(err)) }
    }
}

The stream holds no data of its own, so it can be mixed with the other reads and with writes, and leaving the loop early loses nothing. It keeps the connection open until it has finished or is released.