sync/TcpAcceptor · Standard Library

Listening TCP acceptor wrapper for incoming connections.

Handle and result model

Default construction creates an invalid acceptor handle.
makeTcpAcceptor (address port -- acceptor result) is the platform factory behind listenTcp: it creates the non-blocking listening socket for the host-order IPv4 address and port and returns the acceptor with the empty result string on success, or an invalid acceptor with the failure text. Programs normally call listenTcp.
valid? reports only whether the wrapper holds one non-invalid listening handle.
A valid TcpAcceptor owns one listening socket. Destroying it closes that socket.

Methods

`valid?`

(-- valid) Reports whether the handle refers to one listening acceptor.

(-- connection address result) Waits for one incoming connection and returns one connection wrapper, the remote IPv4 address as one host-order Nat32, and one result string. In DEBUG builds the acceptor must be accessed through a mutable Ref, for example @acceptor.accept; that form also works when DEBUG is FALSE.

Preconditions

The handle is valid.

Accept semantics

accept is one blocking sync-level wait.
An empty result string means success. A non-empty result string means cancellation or failure; the returned connection is then invalid and the address is not meaningful.
accept returns when one connection is accepted, cancellation is observed, or an error is produced.
"canceled" means cancellation was observed before a successful accept completed.
Any other non-empty result string is an error description.
A successful accept leaves the acceptor valid for later accepts until it is destroyed.
In DEBUG builds, overlapping accept calls on one acceptor fail an assertion; likewise overlapping reads or overlapping writes on one connection, while one read and one write may overlap.
On Linux, a parked accept also resumes when the socket reports an error or a hangup and then reports its result. On Windows, an immediately successful AcceptEx is not itself an error; an accept in flight is finalized even after a cancellation request: a successful finalization returns the accepted connection, and if the finalization fails while the context is canceled, the incomplete connection is closed and the result is "canceled". Accepted sockets are put in nonblocking mode.
The returned address is one host-order IPv4 Nat32 value.

macOS backend

macos/sync/TcpAcceptor waits for readability with one EVFILT_READ | EV_ADD | EV_ONESHOT kqueue registration.
The listening socket is made nonblocking with fcntl; an accepted socket is configured with SO_NOSIGPIPE, O_NONBLOCK, and TCP_NODELAY.
Cancellation removes the pending read event with EV_DELETE and resumes the waiting fiber. A canceled accept returns result string "canceled" and an invalid connection.
Debug builds reject concurrent calls to accept on the same acceptor.

Examples

Accept one connection and print the remote address

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

{} Int32 {} [
  server: [
    result: String;
    acceptor: 0x7F000001n32 6612n16 listenTcp !result;
    [result.size 0 =] "listenTcp failed" ensure
    connection: address: @acceptor.accept !result;;
    [result.size 0 =] "accept failed" ensure
    address ipv4ToString print
    LF print
  ];

  client: [
    result: String;
    connection: 0x7F000001n32 6612n16 connectTcp !result;
    [result.size 0 =] "connectTcp failed" ensure
  ];

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

Expected Output

127.0.0.1