Handle and result model

• Default construction creates an invalid connection handle.
• Connection-creation helpers return a valid connection on success.
• valid? reports only whether the wrapper holds one non-invalid connection handle.
• Peer closure is surfaced by read operations, not by valid? directly.
• read returns one transferred byte count together with one result string.
• readString returns one received String together with one result string.
• write and shutdown return one result string only.
• The empty result string means success. Any non-empty result string means graceful closure, cancellation, or failure according to the specific operation.
• A valid TcpConnection owns one connected stream. Destroying it closes that stream.

Methods

• valid?
• read
• readString
• write
• shutdown

Data transfer semantics

• read borrows one caller-owned mutable Nat8 Span and writes received bytes into that storage.
• readString allocates the returned String itself and sizes it to the transferred byte count.
• write borrows one source convertible to Nat8 Cref Span and reads bytes from that view without taking ownership.
• read may return any positive byte count not greater than the destination span size on success.
• A read that transfers no payload bytes is reported as graceful closure through result string "closed".
• shutdown closes only the sending side. The wrapper remains valid and may still report later read-side closure.
• read and readString may return "canceled" when cancellation is observed before a successful read result is produced.
• write may return "canceled" when cancellation is observed before a successful full write result is produced.
• Any other non-empty result string is an error description.

Examples

Send one request and read one reply

"sync/sync" use
"String" use
"control" use

{} Int32 {} [
  server: [
    result: String;
    acceptor: 0x7F000001n32 6613n16 listenTcp !result;
    [result.size 0 =] "listenTcp failed" ensure
    connection: address: acceptor.accept !result;;
    [result.size 0 =] "accept failed" ensure
    message: 32 @connection.readString !result;
    [result.size 0 =] "readString failed" ensure
    "reply" @connection.write !result
    [result.size 0 =] "write failed" ensure
  ];

  client: [
    result: String;
    connection: 0x7F000001n32 6613n16 connectTcp !result;
    [result.size 0 =] "connectTcp failed" ensure
    "hello" @connection.write !result
    [result.size 0 =] "write failed" ensure
    message: 32 @connection.readString !result;
    [result.size 0 =] "readString failed" ensure
    message print
    LF print
  ];

  serverContext: @server () spawn;
  clientContext: @client () spawn;
  @serverContext.wait
  @clientContext.wait
  0
] "main" exportFunction

Expected Output

reply

See also

• sync/sync: Cross-platform scheduling, sleep, time, IPv4 formatting, and TCP helpers.
• sync/TcpAcceptor: Listening TCP acceptor with address reporting and accepted connection creation.
• String: UTF-8 string views, owned strings, formatting helpers, and text conversion utilities.
• linux/socket: Linux socket declarations, constants, address schemas, and imported functions.
• windows/ws2_32: Winsock2 declarations for sockets, overlapped I/O, and address-resolution helpers.