Systems Index | Previous: POSD Module Structure | Next: Core Hot Path

Core design decisions¶

What this chapter defines — The Core's key design decisions, such as asynchronous I/O and the shape of the socket API, and the reasons behind them.

1. Design decision overview¶

This document records the Core's key design decisions and their rationale. The document that owns each contract, rather than this document, defines the exact behavior that each decision guarantees to applications—this document records only what was decided and why.

Decision	Document that owns the contract and details
Asynchronous I/O	Core runtime architecture
Message ownership	Message
Multipart atomicity	Message
Typed socket surface	Socket common specification
Eventing separation	Events, Polling, Monitoring

2. Asynchronous I/O¶

The Core's asynchronous I/O is built on Boost.Asio. Boost.Asio provides a single completion-based I/O model across supported network transports: I/O operations are requested first, and their completion is reported later.

The engine keeps protocol parsing and transport operations behind the session interface. A session is an internal object that represents one transport connection. Core runtime architecture describes the internal structure of the engine and sessions.

3. Message ownership¶

Small payloads are stored inline in the message structure, while large payloads use shared storage referenced by multiple message handles. Explicit move, copy, and close operations express ownership across the C API boundary without exposing allocator selection.

4. Multipart atomicity¶

A multipart array that groups multiple frames (parts) into one logical message remains one call and one logical queue operation. The send code for each socket type delegates admission and ownership of the complete array to the common multipart path. If the call fails, the common path consumes every input slot and exposes no part to the peer, so each socket type's send code needs no partial-submit cleanup.

5. Typed socket surface¶

Pattern-specific metadata is returned through typed APIs. Routing IDs (byte sequences by which a ROUTER socket identifies a specific peer), topics, request sequences, and subscription state are not inserted into application payload frames.

6. Eventing separation¶

The poller reports readiness (the state in which it is worthwhile for a source to proceed with receive or send), the monitor reports transport/protocol transitions, and the generic timer reports time events. These three mechanisms do not interpret application payloads.

Systems Index | Previous: POSD Module Structure | Next: Core Hot Path