한국어 | 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¶
An empty application pipe admits one complete message larger than the HWM, provided that the message does not exceed the socket's maximum message size, and then stops subsequent writes. This exception does not apply to an unfinished multipart message.
3.3 Pending-request lifecycle state¶
Pending-map entries, callbacks, and timeout state grow with the number of live requests. The pending-request admission limit uses a per-physical-pair 32 MiB size-weighted work budget and unresolved-request count limit of 16,384 to bound completion liveness. Work charge is neither actual allocator bytes nor retained payload bytes and is not included in queue-HWM current or snapshot values. Application HWM limits only frames resident in the queue and is not reused as a separate lifecycle limit for unresolved correlation.
3.4 Completion progress lane¶
The ROUTER-ROUTER completion progress lane is a separate path that advances terminal replies and error replies and synchronizes receive-flow-state frames between peers. Byte HWM, LWM, manual HWM, and Core budget reservation do not apply to this lane. Even when an application pipe is full, valid completion records and receive-flow-state frames are admitted if the connection remains available and allocation succeeds.
DEALER-ROUTER has no separate connection. Reply and error-reply bytes are included in the accounted bytes of the same Application physical queue as DATA and REQUEST and apply HWM and peer PAUSED.
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 ABI-reserved fields
application_accounted_bytes, outstanding_application_lease_count,
deferred_origin_credit_bytes, and retired_queue_count are always zero. 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
- Sending an empty application pipe a complete message that is within the socket's maximum message size but larger than the HWM admits one message and then stops subsequent writes.
- The empty-pipe oversize exception does not apply to an unfinished multipart message.
- Even when a ROUTER-ROUTER application pipe is full, a valid reply or error reply is admitted on the Completion lane if the connection remains available and allocation succeeds.
- RUNNING and PAUSED receive-flow-state frames are synchronized over the single Application connection's Core control path on DEALER-ROUTER and over the Completion lane on ROUTER-ROUTER.
- Byte HWM, LWM, manual HWM, and Core budget reservation do not apply to the ROUTER-ROUTER completion progress lane.
- DEALER-ROUTER replies and error replies are included in Application physical-queue bytes and apply HWM and PAUSED. They are not included in Completion current, peak, or pending 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.