Executor - API reference

Abstract base for connection-dispatch strategies. The concrete strategy today is thread-per-connection-executor; a pooled or coroutine executor subclasses this later without touching the event loop or handlers.

Runs each connection's whole lifetime SYNCHRONOUSLY on the calling thread: no worker thread, no per-connection lifecycle. The connectionless, one-shot transports take this path: a UDP datagram arrives already fully in hand, so there is nothing to read-block on and nothing to keep alive. Spawning a thread per datagram would only hand an off-path packet flood an unbounded thread- creation lever; dispatching inline bounds the work to the caller's own thread. dispatch-connection returns only after the handler has run and the connection is closed, so the caller (the mux loop thread) IS the execution context.

Spawns a new OS thread per accepted connection. The mux thread returns as soon as make-thread returns: the worker thread owns the connection's fd from that point and calls the registry's dispatch-connection on the worker stack. A pooled or coroutine executor is a future subclass of executor; that swap does not touch the multiplexer or any protocol handler.

Signalled when an executor generic is called on a class that has not specialised dispatch-connection. A concrete executor is a promise to put a connection on a runnable execution context; this condition marks the broken promise rather than letting it pass silently.

(dispatch-connection executor connection)

Dispatch CONNECTION to its protocol handler. Must return immediately: the event-dispatch loop thread calls this and must not block. The implementation is responsible for routing through the registry on whatever execution context it manages (worker thread, pool, coroutine). Distinct from valis/src/registry:dispatch-connection: this generic schedules; the registry function looks up the protocol and invokes handle-connection.

(executor-not-implemented-executor condition)

Undocumented: this exported symbol needs a docstring.

(make-inline-executor)

Construct an inline executor, the connectionless one-shot dispatch strategy.

(make-thread-executor)

Construct a thread-per-connection executor, the current concrete strategy.

(serve-connection port connection &key (registry *registry*))

Route CONNECTION, which arrived on PORT, through REGISTRY to its protocol's handler on the calling thread, and answer T when the handler returned or NIL when the connection was abandoned. Closing CONNECTION is left to the caller.

Every executor serves a connection through this, so a failure ends only the connection it arose in, wherever that connection runs. A peer that drops its connection ends it quietly, logged at debug level with its condition class and message. Dropping it covers a reset, a write after the peer has gone, a hang-up, a poll that finds the descriptor in error, and the peer ending its input before the exchange is complete. A port nothing claims any longer is logged as a warning naming the port. Anything else the handler signals is a defect: it is logged at error level with its condition class and a backtrace from where it was signalled, and only this connection ends.