한국어 | English
Systems Index | Previous: Thread Safety | Next: Auto HWM
Connection Memory¶
What this chapter defines — how much memory a single connection actually allocates (fixed costs and variable costs proportional to the HWM).
1. Connection memory overview¶
Each transport connection uses two kinds of memory. One is the fixed cost allocated when the connection is created. Its components differ between inproc and socket-based transports. The other is the variable cost of message storage retained by queues and pending-request lifecycle state. It is not a fixed connection cost. Queue storage grows with each frame's actual accounted bytes and the HWM, which limits the bytes retained in a queue.
This document defines the components of these two costs and the limitations of observing and measuring them. Its intended audience is developers who estimate per-connection memory usage and perform capacity planning.
The following documents own the related contracts.
| Related contract | Defining document |
|---|---|
| Memory budget calculation, byte accounting, and HWM admission | Auto HWM |
| socket options and HWM observation behavior | Socket Common |
| Short definitions of terms | Core Glossary |
2. Fixed components¶
The components allocated when a connection is created, regardless of traffic volume, differ by transport as follows.
| Transport | Fixed components |
|---|---|
| inproc | A pipepair that directly connects two socket endpoints. It creates no session or engine and has no protocol handshake state or operating-system socket. |
| Socket-based transport | Session, engine, pipe endpoints and queue chunks, routing ID and endpoint metadata, protocol handshake state, and operating-system socket structures. TLS adds record and handshake storage. |
3. Variable components¶
Contract owner for this section — Auto HWM owns the public contracts and internal implementation for byte accounting, HWM admission, and budget calculation. This section summarizes their results from the perspective of the memory cost of one connection.
3.1 Frame byte charge¶
A physical queue that stores messages for one application direction is called a
directional queue. The variable memory of one connection
is the byte charge of the frames this queue currently holds. The charge formula (payload plus
sizeof(zlink_msg_t)), the provisional-to-committed transition, and the return points are owned by
Auto HWM's physical queue accounting; this document
only cites the result: a charge is part of the connection's memory cost only while the frame is in
the queue, and a binding or application holding the payload after dequeue does not add to it.
3.2 Empty-pipe oversize exception¶
Empty-pipe complete-message admission and subsequent write blocking follow Auto HWM message processing order.
3.3 Pending-request lifecycle state¶
Pending-map entries, callbacks, and timeout state grow with the live request count. Per-pair work and count admission limits and reservation release follow Auto HWM pending-request admission.
3.4 Completion progress lane¶
The ROUTER-ROUTER completion progress lane separately carries terminal replies, error replies, and receive-flow-state frames. HWM and accounting for this lane and the DEALER-ROUTER Application queue follow Auto HWM §2 completion-lane HWM and accounting.
The completion lane preserves the SNDBUF/RCVBUF default of -1, leaving OS defaults and
autotuning unchanged for every transport. When the application supplies a nonnegative value, Core
caps it at 64 KiB for the completion lane and applies it consistently to the underlying TCP socket
for TCP, TLS, WS, and WSS.
4. Measurement and limitations¶
The monitor that reports runtime memory state separately exposes current bytes for application queues and completion lanes, as well as oversize-admission history. The snapshot's ABI-reserved fields and returned values follow the budget-snapshot contract in Auto HWM §3. The Core budget — the total number of bytes that Core uses as the basis for distributing HWM among application queues after calculating it from memory inputs — is the normal-state basis for distributing per-pipe HWM, not a hard cap on actual context memory usage. This value explains Core accounting but is not an exact measurement of process resident memory.
Kernel buffers may grow according to platform autotuning. TLS adds record and handshake storage. Monitor snapshots report the applied HWM plan but do not measure all allocator and kernel overhead.
Because DEALER-ROUTER uses one physical connection per logical peer, it uses one fewer idle session, engine, and file descriptor, and one connection less of underlying kernel, TLS, or WebSocket storage than ROUTER-ROUTER. This difference does not turn the Core budget into a hard cap on process resident memory or change the boundary that places kernel autotuning and TLS storage outside the monitor snapshot.
5. Capacity planning¶
Capacity planning measures each of the following three values using the production transport and message-size distribution.
- Idle memory
- Residual memory after traffic
- Burst peak memory
6. Implementation and contract-test verification requirements¶
Auto HWM verification requirements own the detailed verification items for byte accounting, admission, dequeue credit, and the oversize exception. From the connection-memory perspective, verify the following items. Each item maps to one test.
Byte charge and HWM
- The observable items for frame-charge increase, transition and return, and for HWM admission, are owned by Auto HWM §5. This document does not repeat them.
Oversize and completion - Empty-queue oversize and pending-request admission verification refer to Auto HWM verification. - Completion-lane carriage refers to ZMP request-reply lanes; HWM and accounting refer to Auto HWM §2 completion-lane HWM and accounting.
Measurement
- The monitor separately reports current bytes for application queues and completions, as well as oversize-admission history, and reports the retained-credit compatibility fields as zero.
- The Core budget is the normal-state basis for distributing per-pipe HWM and does not act as a hard cap on actual context memory usage. Auto HWM owns the detailed admission contract.
- On the same transport, a DEALER-ROUTER logical peer uses one physical connection and a ROUTER-ROUTER logical peer uses two. Observing the reduction in idle resources does not provide a process hard cap that includes allocator, kernel, and TLS memory.