Systems Index | Previous: Systems Overview | Next: Threading Model

Core runtime architecture¶

What this chapter defines — the internal components and boundaries that messages traverse from the public C API to the I/O threads.

1. Core runtime overview¶

Core is a raw socket runtime. The public C API enters the implementation of a socket — an endpoint that exchanges messages — and the socket implementation exchanges commands and messages with I/O thread objects — background threads that perform the actual network send and receive operations — through mailboxes that carry commands across thread boundaries and pipes that carry messages.

The components are stacked in the following layers.

+------------------------------------------------------+
| Public C API                                         |
+------------------------------------------------------+
| Socket patterns and eventing                         |
+------------------------------------------------------+
| Context, socket base, sessions, pipes, mailboxes     |
+------------------------------------------------------+
| ZMP or raw engines                                   |
+------------------------------------------------------+
| TCP, IPC, inproc, WebSocket, TLS transports          |
+------------------------------------------------------+

This document describes only the internal structure of these components (implementation description — when the implementation changes, update this document to match the code). Its intended audience is Core maintainers. The following documents, rather than this document, own the public contracts that each component exposes.

Related contract	Defining document
Responsibility boundary that keeps Core a raw socket runtime only	Runtime Boundary
Context lifetime and options	Context
Socket creation, options, sending, and receiving	Socket Common
Socket monitor contract	Monitoring
Utilities such as pollers and timers	Utilities

2. Context and threads¶

Context is the top-level container for I/O threads and sockets. Its implementation, ctx_t, owns socket slots, I/O threads, a reaper thread dedicated to the final cleanup of closed sockets, the endpoint registry, and a per-context generic control runtime that drives internal monitor queue delivery and Auto HWM recalculation. Generic timers are managed by a process-global timer scheduler.

Socket closure sends a termination command and waits until the owned objects release their resources.

3. Socket and session path¶

socket_base_t owns public socket state and pattern-specific behavior. A session is an internal object that represents one transport connection. A pipe carries messages between the socket thread and session or engine objects while preserving multipart order.

4. Engines and transports¶

The Asio engine submits asynchronous reads and writes and receives completion callbacks. The ZMP engine encodes zlink message frames, while the raw engine passes byte-stream payloads. Transport classes handle endpoint parsing, connection establishment, and operating-system I/O.

5. Eventing¶

The poller combines readiness for sockets, file descriptors, and generic timers in one place. The socket monitor observes raw transport and protocol transitions. The control runtime drives internal monitor queue delivery and Auto HWM recalculation outside the socket I/O threads. The generic timer scheduler records fire counts in a queue, and the application reads them with zlink_timer_recv().

Systems Index | Previous: Systems Overview | Next: Threading Model