Connection - API reference

Abstract connection handle. Carries the fields common to every transport the listener accepts. Concrete transports subclass this: tcp-connection adds the iolib socket; datagram-connection adds the received payload and peer port. The abstract class is never instantiated directly.

A datagram (UDP) connection delivered by the listener. Does not offer a stream view: datagrams have no stream semantics, and forcing one would require buffering machinery UDP does not earn. Carries the source's UDP socket as an opaque reply handle so the answer can leave through the backend's reply-datagram, aimed at the exact peer address/port receive-from recovered.

A stream (TCP) connection accepted by the listener. The stored socket is already a bivalent Gray stream; the stream view is vended on demand through connection-stream at zero allocation cost.

Signalled when connection-stream is called on a transport that has no stream semantics — currently only datagram connections.

(abort-pending-read connection)

Wake any reader currently blocked on CONNECTION's stream so it observes end-of-file. The default method is a no-op. The TCP method lives in the epoll backend — the one place allowed to name iolib — because waking the reader takes a transport-level shutdown(2) of the socket's read side; that is the only call that reliably unblocks a thread parked in the socket library's internal poll loop.

(close-connection connection)

Release any operating-system resources the connection holds. For TCP the executor worker owns the fd from dispatch-connection onward: once the handler returns or throws, the worker must call close-connection so the accepted client socket is released back to the kernel — without this, every accepted connection leaks an fd for the lifetime of the process. For datagram connections this is a no-op: the per-datagram connection holds only a payload buffer; the underlying UDP socket lives on the datagram-source, not on the connection. The generic stays transport-blind so the executor never has to name the iolib socket itself.

(connection-destination-port object)

Undocumented: this exported symbol needs a docstring.

(connection-fd object)

Undocumented: this exported symbol needs a docstring.

(connection-payload object)

Undocumented: this exported symbol needs a docstring.

(connection-peer-address object)

Undocumented: this exported symbol needs a docstring.

(connection-peer-port object)

Undocumented: this exported symbol needs a docstring.

(connection-principal object)

Undocumented: this exported symbol needs a docstring.

(connection-read-deadline-expired-p connection)

Return T when CONNECTION's read deadline passed before its reads completed. Handlers call this after a read returns end-of-file to decide between deadline semantics (HTTP 408, silent Gopher close) and ordinary peer-close semantics. Always nil for connections that cannot carry a deadline.

(connection-socket object)

Undocumented: this exported symbol needs a docstring.

(connection-stream connection)

Return the bivalent (binary + character, in + out) stream for CONNECTION. Valid only for TCP connections; the returned object is the iolib dual-channel-gray-stream the accepted socket already IS, so callers get read-line/read-sequence/write-sequence/write-char at the stream level with no allocation. Signals STREAM-NOT-AVAILABLE for datagram connections — datagrams have no stream semantics.

(connection-transport-kind object)

Undocumented: this exported symbol needs a docstring.

(connection-udp-socket object)

Undocumented: this exported symbol needs a docstring.

(set-read-deadline connection seconds)

Arm a read deadline on CONNECTION: if the peer has not satisfied the handler's reads within SECONDS, the pending read is aborted so the handler thread observes end-of-file instead of blocking forever on a silent or dribbling client. Expiry also sets the flag read by connection-read-deadline-expired-p, letting the handler distinguish a cut-off from an ordinary client close. The default method is a no-op so transports with nothing to time out — datagram connections, in-memory test connections — accept the call harmlessly. Returns the armed timer for TCP connections, nil otherwise.

(stream-not-available-connection condition)

Undocumented: this exported symbol needs a docstring.

(make-datagram-connection &key fd destination-port peer-address transport-kind payload peer-port udp-socket)

Construct a datagram connection with port validation. TRANSPORT-KIND must be :datagram. DESTINATION-PORT and PEER-PORT must be in (unsigned-byte 16). UDP-SOCKET is the datagram-source's socket, carried opaquely so a reply can be sent back to the peer; it may be nil for a datagram with no reply path.

(make-tcp-connection &key fd destination-port peer-address transport-kind socket)

Construct a TCP connection with port validation. TRANSPORT-KIND must be :stream. DESTINATION-PORT must be in (unsigned-byte 16).