Appearance
file FlakeLimits.h
Defines
| Name | |
|---|---|
| FLAKE_MAX_CONNECTIONS | Maximum number of concurrent client Connection instances. |
| FLAKE_MAX_OBJECTS | Maximum number of cached ObjectImpl / ServersideObject instances per side of the protocol. |
| FLAKE_MAX_PROPERTIES | Total number of Property slots the shared PropertyPool can hold across the entire process. |
| FLAKE_DEFERRED_SLOTS | Deferred snapshots (slots) per object. |
| FLAKE_DEFERRED_POOL_RESERVE | Property slots defer() leaves to everything else in the pool. |
| FLAKE_DEFERRED_OFFSET_ENTRIES | Per-slot entries of the timestamp-offset table (one per distinct tag merged into the slot after it was opened). When it is full the next defer() opens a new slot instead of losing the tag's time. |
| FLAKE_DEFERRED_OFFSET_TABLES | Offset tables shared by all objects. |
| FLAKE_REPORT_BUFFER_BYTES | Fixed report storage for value history, in bytes; 0 keeps the history buffers in the shared byte pool. |
| FLAKE_MAX_PRIO_RANGES | Tag ranges per object for Object::setPriority and Object::setHistoryClass, each. |
| FLAKE_MAX_PEER_SESSIONS | Streams the peer may hold open on one object at a time, counted per opener (two openers of one stream are two sessions). Further sessions work but are not counted. RAM cost: 16 bytes per entry inside every ObjectImpl. |
| FLAKE_MAX_ROUTERS | Maximum number of concurrent Router instances in a process. |
| FLAKE_MAX_STREAMS_PER_OBJECT | Maximum number of open Stream objects per ObjectImpl. |
| FLAKE_MAX_SERVER_WIRES | Total cap on live ServerWire instances in the process. |
| FLAKE_MAX_PENDING_REPLIES | Maximum number of outstanding request/reply correlation slots per Transport. Protocol-level cap — bounds how many in-flight requests one Transport may have awaiting a CONF. |
| FLAKE_MAX_PENDING_INDICATIONS | Maximum number of outstanding indication tokens per Transport. Bounds how many in-flight indications one Transport tracks. |
| FLAKE_MAX_MESSAGE_PAYLOAD | Maximum accepted payload size (bytes) of a single received Message. |
| FLAKE_POOL_TINY_SIZE | |
| FLAKE_POOL_TINY_COUNT | |
| FLAKE_POOL_SMALL_SIZE | |
| FLAKE_POOL_SMALL_COUNT | |
| FLAKE_POOL_MEDIUM_SIZE | |
| FLAKE_POOL_MEDIUM_COUNT | |
| FLAKE_POOL_LARGE_SIZE | Large bucket: slot width and count. |
| FLAKE_POOL_LARGE_COUNT | |
| FLAKE_MAX_WIRES | Total cap on live Wire instances in the process. |
| FLAKE_MAX_STREAMS | Total maximum of live StreamImpl instances across all objects. Derived from the per-object Stream cap and the object pool. |
| FLAKE_MAX_MESSAGES | Maximum number of Flake protocol Message objects in flight across the whole process. |
| FLAKE_MAX_PROPARRAYS | Maximum number of live PropArray instances registered with the shared PropertyPool. |
| FLAKE_MAX_DIRECTORY_ENTRIES | Maximum number of entries in an ObjectTree's directory. |
| FLAKE_ARENA_BYTEPOOL_BYTES | Exact total bytes the size-class byte buckets will need. |
Macros Documentation
define FLAKE_MAX_CONNECTIONS
cpp
#define FLAKE_MAX_CONNECTIONS 4UMaximum number of concurrent client Connection instances.
Default is 4U — enough to host router + two clients in one process for the quality-pipeline test binaries, and a modest margin for production builds. Tight single-client MCU deployments override this explicitly (-DFLAKE_MAX_CONNECTIONS=1).
RAM cost per slot: sizeof(ConnectionImpl) ≈ 1 KiB + 64 B * FLAKE_MAX_OBJECTS (the SubscriptionEntry FixedVector grows with the object cap). On a router build add sizeof(ServerConnection) ≈ 3.8 KiB per slot. So at FLAKE_MAX_OBJECTS=8 each connection costs ~5.3 KiB client-side, ~9 KiB on a router build; at FLAKE_MAX_OBJECTS=24, ~7.9 KiB / ~12 KiB.
define FLAKE_MAX_OBJECTS
cpp
#define FLAKE_MAX_OBJECTS 8UMaximum number of cached ObjectImpl / ServersideObject instances per side of the protocol.
Both the client-side ObjectImpl pool and the router-side ServersideObject pool are sized to this cap. The total live object count in a process therefore approaches 2 * FLAKE_MAX_OBJECTS in a router-plus-clients deployment.
RAM cost per slot: sizeof(ObjectImpl) ≈ 820 B (5 PropArray handles + per-slot offset sidecars + stream FixedVector). sizeof(ServersideObject) ≈ 100 B (router only). Note that ConnectionImpl, Router, and the directory-table sizes also scale with this cap — a higher value indirectly grows several containers besides the object pools.
define FLAKE_MAX_PROPERTIES
cpp
#define FLAKE_MAX_PROPERTIES 256UTotal number of Property slots the shared PropertyPool can hold across the entire process.
This is the single largest memory footprint the library has: every ObjectImpl's properties, cache, and deferred snapshots, plus every in-flight Message's payload, draw their Property slots from here. Sized for the realistic steady state, not the absolute worst case.
RAM cost per slot: ~52 B fixed (Property struct + slot-used flag + sequence index + owner byte). Variable-length payloads (strings, blobs, arrays) are drawn from the FLAKE_POOL_* byte buckets separately — a 12-char string costs 52 B (slot) + 32 B (TINY bucket); a 300-byte blob costs 52 B + 512 B (MEDIUM bucket); etc. Scalar properties (uint32, bool, int64, float) only consume the 52 B slot.
define FLAKE_DEFERRED_SLOTS
cpp
#define FLAKE_DEFERRED_SLOTS 3UDeferred snapshots (slots) per object.
A slot holds one report window's values plus their offsets and history. A new slot opens when a defer() cannot merge into the newest one: the window spans more than 18 h, its offset table is full, or a value that has no history encoding (array, null, error) would be overwritten. With every slot taken the oldest one is dropped and counted, so devices that record arrays or many distinct tags per window need more than the default. RAM cost per slot: one PropArray registration plus 8 bytes inside the ObjectImpl; the offset table comes from a shared pool, see FLAKE_DEFERRED_OFFSET_TABLES.
define FLAKE_DEFERRED_POOL_RESERVE
cpp
#define FLAKE_DEFERRED_POOL_RESERVE (FLAKE_MAX_PROPERTIES / 8U)Property slots defer() leaves to everything else in the pool.
Deferred snapshots draw from the pool that also holds the property stores, every message in flight and every request from the peer. Without this floor an object that defers through an outage fills the pool to the last slot; after the reconnect the first block of the next registration and the peer's requests find no room. In the field that kept device services from ever sending their identity. A value defer() cannot place stays dirty in the store and goes out with the next sync, stamped with the send time.
A sync holds each value twice until its message is built and cuts the message short when the pool has no room for both copies, so at the floor a message carries half the free slots minus four meta properties. An eighth of the pool leaves a dozen values per message and room for the peer's requests; every slot more is taken from the deferred buffer, whose values keep their own time.
define FLAKE_DEFERRED_OFFSET_ENTRIES
cpp
#define FLAKE_DEFERRED_OFFSET_ENTRIES 64UPer-slot entries of the timestamp-offset table (one per distinct tag merged into the slot after it was opened). When it is full the next defer() opens a new slot instead of losing the tag's time.
Every tag that changes during a report window needs an entry in the slot that holds its newest value; a window with more changing tags than entries spreads over several slots and, once all slots are taken, values fall back to the slot's base time. 64 covers the ~40 tags a busy device changes per window. RAM cost: 4 bytes per entry and table.
define FLAKE_DEFERRED_OFFSET_TABLES
cpp
#define FLAKE_DEFERRED_OFFSET_TABLES (2U * FLAKE_DEFERRED_SLOTS)Offset tables shared by all objects.
A slot takes a table when it records its first offset and returns it once the slot is empty, so only objects with an open report window hold one, usually one each. Proxies and objects that never defer hold none. Without a free table a defer() opens a new slot, whose own base time is exact; only with every slot taken does a value fall back to the slot's base time, counted in Object::reportFill. RAM cost: 4 * FLAKE_DEFERRED_OFFSET_ENTRIES bytes per table.
define FLAKE_REPORT_BUFFER_BYTES
cpp
#define FLAKE_REPORT_BUFFER_BYTES 0UFixed report storage for value history, in bytes; 0 keeps the history buffers in the shared byte pool.
A 20-minute window on a busy device collects ~1.500 samples, 5–9 KB of history. In the byte pool such a buffer outgrows the largest bucket and lands in the arena overhang, which a tightly sized arena does not have; samples are then dropped. A non-zero value carves this many bytes from the arena as a dedicated store that all objects share, so the peak is fixed at build time and ObjectDelegate::onReportPressure reports how full it is.
define FLAKE_MAX_PRIO_RANGES
cpp
#define FLAKE_MAX_PRIO_RANGES 8UTag ranges per object for Object::setPriority and Object::setHistoryClass, each.
define FLAKE_MAX_PEER_SESSIONS
cpp
#define FLAKE_MAX_PEER_SESSIONS FLAKE_MAX_STREAMS_PER_OBJECTStreams the peer may hold open on one object at a time, counted per opener (two openers of one stream are two sessions). Further sessions work but are not counted. RAM cost: 16 bytes per entry inside every ObjectImpl.
define FLAKE_MAX_ROUTERS
cpp
#define FLAKE_MAX_ROUTERS 1UMaximum number of concurrent Router instances in a process.
The flakeInitializeWithRouter entry point is a singleton, so 1U is the only sensible default. Integrators that host multiple isolated Flake sub-systems in one process override this.
RAM cost per slot: sizeof(Router) ≈ 1.2 KiB + scaling with FLAKE_MAX_OBJECTS via the directory FixedVector (≈ 16 B per directory entry × 4 × FLAKE_MAX_OBJECTS). Default sizes ≈ 1.2 KiB at 8 objects, ≈ 2.7 KiB at 24 objects.
define FLAKE_MAX_STREAMS_PER_OBJECT
cpp
#define FLAKE_MAX_STREAMS_PER_OBJECT 2UMaximum number of open Stream objects per ObjectImpl.
RAM cost per stream: sizeof(StreamImpl) ≈ 1.2 KiB (dominated by the ring buffer that backs in-flight stream chunks). Total cost is per-stream × FLAKE_MAX_STREAMS, not per-object × this knob.
define FLAKE_MAX_SERVER_WIRES
cpp
#define FLAKE_MAX_SERVER_WIRES 4UTotal cap on live ServerWire instances in the process.
Backs both the shared ServerWirePool slot count (see WirePool.cpp) and the Router's per-instance m_serverWires FixedVector. Each transport a router speaks contributes one ServerWire, one accept thread, and one done-semaphore. Default 4U covers simultaneous TCP + UDP + Serial + IPC listeners on one router; raise it for TLS variants or multi-router setups.
RAM cost per slot: ~280 B (max sizeof over ServerWire subclasses, dominated by UdpServerWire whose connection map scales with FLAKE_MAX_WIRES).
define FLAKE_MAX_PENDING_REPLIES
cpp
#define FLAKE_MAX_PENDING_REPLIES 10UMaximum number of outstanding request/reply correlation slots per Transport. Protocol-level cap — bounds how many in-flight requests one Transport may have awaiting a CONF.
RAM cost: this knob does not allocate a pool of its own — it caps one of the FixedVectors inside Transport (a member of every Connection). Higher values grow sizeof(ConnectionImpl) by ~24 B per added slot.
define FLAKE_MAX_PENDING_INDICATIONS
cpp
#define FLAKE_MAX_PENDING_INDICATIONS 10UMaximum number of outstanding indication tokens per Transport. Bounds how many in-flight indications one Transport tracks.
RAM cost: see FLAKE_MAX_PENDING_REPLIES — same shape, same per-slot cost (~24 B added to sizeof(ConnectionImpl)).
define FLAKE_MAX_MESSAGE_PAYLOAD
cpp
#define FLAKE_MAX_MESSAGE_PAYLOAD 2048UMaximum accepted payload size (bytes) of a single received Message.
A deserialised header claiming a larger payload is rejected before m_payloadBuf grows. The default matches FLAKE_POOL_LARGE_SIZE (keep the two in sync) so the payload always fits a freeable byte-pool bucket. That bounds two failure modes from a crafted length field: the halt-on-exhaustion DoS (an unservable allocation), and the per-message leak from spilling m_payloadBuf into the bump-only arena overhang (which flakeFree cannot reclaim). Deployments that reassemble larger messages raise this together with FLAKE_POOL_LARGE_SIZE and size the arena accordingly. It comfortably covers scalar/short-string properties and a typical queryObjects table response.
define FLAKE_POOL_TINY_SIZE
cpp
#define FLAKE_POOL_TINY_SIZE 32Udefine FLAKE_POOL_TINY_COUNT
cpp
#define FLAKE_POOL_TINY_COUNT 16Udefine FLAKE_POOL_SMALL_SIZE
cpp
#define FLAKE_POOL_SMALL_SIZE 128Udefine FLAKE_POOL_SMALL_COUNT
cpp
#define FLAKE_POOL_SMALL_COUNT 16Udefine FLAKE_POOL_MEDIUM_SIZE
cpp
#define FLAKE_POOL_MEDIUM_SIZE 512Udefine FLAKE_POOL_MEDIUM_COUNT
cpp
#define FLAKE_POOL_MEDIUM_COUNT 8Udefine FLAKE_POOL_LARGE_SIZE
cpp
#define FLAKE_POOL_LARGE_SIZE 2048ULarge bucket: slot width and count.
Serves the largest variable-length payloads — a property value or a Message reassembly buffer (m_payloadBuf) wider than FLAKE_POOL_MEDIUM_SIZE — plus internal containers that exceed MEDIUM. Wire instances do not come from here: every Wire / ServerWire subclass is served from its own WirePool / ServerWirePool slot via a class-scoped operator``new (see WirePool.cpp). Sizing this off the wire count is therefore wrong.
At LARGE_SIZE × LARGE_COUNT this is the single largest byte-pool contributor (16 KiB of the ~23 KiB default). A client that never carries a payload wider than FLAKE_POOL_MEDIUM_SIZE can drop the count to 0 and let the overhang absorb rare outliers.
define FLAKE_POOL_LARGE_COUNT
cpp
#define FLAKE_POOL_LARGE_COUNT 8Udefine FLAKE_MAX_WIRES
cpp
#define FLAKE_MAX_WIRES (2UL * FLAKE_MAX_CONNECTIONS)Total cap on live Wire instances in the process.
Backs the shared WirePool slot count (see WirePool.cpp). All Wire subclasses (TCP/UDP/Serial/TLS/DTLS/IPC) share one pool; the slot size is max(sizeof(SubT)) over every subclass. Default 2 * FLAKE_MAX_CONNECTIONS — an in-process router pairs every client connection with two IPCWire instances (client-side
- router-side).
RAM cost per slot: with a router ~1.5 KiB (max sizeof, dominated by IPCWire and its inline ring buffer); without one IPCWire is not built and the slot is the largest client wire, ~100 B.
define FLAKE_MAX_STREAMS
cpp
#define FLAKE_MAX_STREAMS (1UL * FLAKE_MAX_STREAMS_PER_OBJECT * FLAKE_MAX_OBJECTS)Total maximum of live StreamImpl instances across all objects. Derived from the per-object Stream cap and the object pool.
RAM cost per slot: sizeof(StreamImpl) ≈ 1.2 KiB. At default sizing (FLAKE_MAX_OBJECTS=8, FLAKE_MAX_STREAMS_PER_OBJECT=2) the pool reserves ~20 KiB.
define FLAKE_MAX_MESSAGES
cpp
#define FLAKE_MAX_MESSAGES ((FLAKE_MAX_CONNECTIONS * \
(FLAKE_MAX_PENDING_REPLIES + FLAKE_MAX_PENDING_INDICATIONS)) / 2U)Maximum number of Flake protocol Message objects in flight across the whole process.
Each Transport can have up to PENDING_REPLIES + PENDING_INDICATIONS slots in flight; with MAX_CONNECTIONS active Transports the absolute worst case is MAX_CONNECTIONS * (PENDING_REPLIES + PENDING_INDICATIONS). The default halves that to reflect the realistic steady state — typical traffic does not fill every slot every Transport simultaneously. Override (or raise the per-Transport caps) if your workload is bursty.
RAM cost per slot: sizeof(Message) ≈ 152 B. The Message's own payload Properties live in the shared PropertyPool — they are counted by FLAKE_MAX_PROPERTIES, not here.
define FLAKE_MAX_PROPARRAYS
cpp
#define FLAKE_MAX_PROPARRAYS (((2U + FLAKE_DEFERRED_SLOTS) * FLAKE_MAX_OBJECTS) + FLAKE_MAX_MESSAGES + 16U)Maximum number of live PropArray instances registered with the shared PropertyPool.
Each ObjectImpl holds 2 + FLAKE_DEFERRED_SLOTS PropArrays (properties + cache + one per deferred slot); each in-flight Message holds 1; plus a small fixed margin for Router-transit and short-lived stack locals.
RAM cost: 8 B per slot (one pointer in the registry). Cheap.
define FLAKE_MAX_DIRECTORY_ENTRIES
cpp
#define FLAKE_MAX_DIRECTORY_ENTRIES (4UL * FLAKE_MAX_OBJECTS)Maximum number of entries in an ObjectTree's directory.
Each registered Node occupies at least one directory slot (own id), optionally one more for its broadcast id, plus one per distinct group membership. Default 4 * FLAKE_MAX_OBJECTS covers id + broadcast + up to two group memberships per object.
define FLAKE_ARENA_BYTEPOOL_BYTES
cpp
#define FLAKE_ARENA_BYTEPOOL_BYTES (static_cast<std::size_t>(FLAKE_POOL_TINY_SIZE) * FLAKE_POOL_TINY_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_SMALL_SIZE) * FLAKE_POOL_SMALL_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_MEDIUM_SIZE) * FLAKE_POOL_MEDIUM_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_LARGE_SIZE) * FLAKE_POOL_LARGE_COUNT)Exact total bytes the size-class byte buckets will need.
Source code
cpp
/*******************************************************************************
* @file FlakeLimits.h
* @brief Compile-time resource caps for the libflake client build.
* @details These macros set the upper bounds for every runtime resource that
* the library would otherwise grow dynamically. They drive the
* size-class byte pool and the per-type object pools, making the
* library heap-free in embedded deployments.
*
* The file has three sections:
*
* 1. **Inputs** — the three knobs an integrator needs to set
* to size a deployment. Defaults target a small MCU.
*
* 2. **Architectural constants** — orthogonal limits that
* govern protocol/topology rather than scale. The
* defaults rarely need touching; an integrator can
* override them when the architectural bound is
* different (e.g. richer group topology, more pending
* ops per Transport).
*
* 3. **Derived caps** — every other limit, computed from
* (1) and (2). Each is still @c #ifndef-guarded so an
* override remains possible, but the common case is
* "set the inputs, accept the derivations".
*
* Validation runs at the bottom of this file: each invariant
* (e.g. "the worst-case deferred state fits in the property
* pool") is checked via @c #if @c #error, so an inconsistent
* override fails at preprocess time rather than at runtime.
*
* The allocator is single-path: @c flakeAlloc never falls back to
* the system heap. Allocations that exceed the pools return
* @c nullptr, which the public API layer maps to @c E_NO_ALLOC.
* Integrators size the macros below to cover the actual working
* set of their deployment. The library's no-heap contract is
* enforced by code review — no runtime canary, no link-time
* @c malloc wraps; every allocation site in this tree must draw
* from the pools or a caller-supplied arena.
*
* ## RAM cost cheat-sheet (per slot, default profile)
*
* Each cap below carries a "RAM cost per slot" annotation.
* Quick reference for the dominant items:
*
* Property slot ~52 B (+ 32–2048 B bytepool for
* string / blob / array
* payloads)
* ObjectImpl ~820 B
* ServersideObject ~100 B (router only)
* ConnectionImpl ~1 KiB + 64 B × FLAKE_MAX_OBJECTS
* ServerConnection ~3.8 KiB (router only)
* StreamImpl ~1.2 KiB
* Message ~152 B (payload Properties draw
* from the Property pool)
* Wire pool slot ~1.5 KiB with router (IPCWire
* and its ring buffer),
* ~100 B without
* ServerWire pool slot ~280 B (router only)
* Router ~1.2–2.7 KiB (scales with object
* cap)
* PropArray registry 8 B per slot
*
* Variable-length payload buckets (@c FLAKE_POOL_*_SIZE ×
* @c FLAKE_POOL_*_COUNT) and the per-pool default backing
* (when @c FLAKE_EXTERNAL_ARENA is OFF) are the other major
* contributors. See the per-knob comments for detail.
*
* @license This file is part of the ImagineOn Flake software package
* licensed under the ImagineOn software-licensing terms available
* under https://www.imagineon.de/de/info/licensing-terms
* @copyright Copyright (c) 2025 ImagineOn GmbH. www.imagineon.de.
******************************************************************************/
#ifndef FLAKE_LIMITS_H
#define FLAKE_LIMITS_H
#include <cstddef>
/* =======================================================================
* SECTION 1 — Inputs
*
* The three knobs that describe the deployment scale. Set these to
* match your worst-case load; the derived caps in section 3 fall out
* automatically.
* ======================================================================= */
#ifndef FLAKE_MAX_CONNECTIONS
# define FLAKE_MAX_CONNECTIONS 4U
#endif
#ifndef FLAKE_MAX_OBJECTS
# define FLAKE_MAX_OBJECTS 8U
#endif
#ifndef FLAKE_MAX_PROPERTIES
# define FLAKE_MAX_PROPERTIES 256U
#endif
#ifndef FLAKE_DEFERRED_SLOTS
# define FLAKE_DEFERRED_SLOTS 3U
#endif
#ifndef FLAKE_DEFERRED_POOL_RESERVE
# define FLAKE_DEFERRED_POOL_RESERVE (FLAKE_MAX_PROPERTIES / 8U)
#endif
#ifndef FLAKE_DEFERRED_OFFSET_ENTRIES
# define FLAKE_DEFERRED_OFFSET_ENTRIES 64U
#endif
#ifndef FLAKE_DEFERRED_OFFSET_TABLES
# define FLAKE_DEFERRED_OFFSET_TABLES (2U * FLAKE_DEFERRED_SLOTS)
#endif
#ifndef FLAKE_REPORT_BUFFER_BYTES
# define FLAKE_REPORT_BUFFER_BYTES 0U
#endif
#ifndef FLAKE_MAX_PRIO_RANGES
# define FLAKE_MAX_PRIO_RANGES 8U
#endif
#ifndef FLAKE_MAX_PEER_SESSIONS
# define FLAKE_MAX_PEER_SESSIONS FLAKE_MAX_STREAMS_PER_OBJECT
#endif
/* =======================================================================
* SECTION 2 — Architectural constants
*
* Orthogonal protocol/topology bounds. These do not scale with the
* deployment size — a tighter or wider deployment leaves them
* unchanged. Override only when the architecture needs it.
* ======================================================================= */
#ifndef FLAKE_MAX_ROUTERS
# define FLAKE_MAX_ROUTERS 1U
#endif
#ifndef FLAKE_MAX_STREAMS_PER_OBJECT
# define FLAKE_MAX_STREAMS_PER_OBJECT 2U
#endif
#ifndef FLAKE_MAX_SERVER_WIRES
# define FLAKE_MAX_SERVER_WIRES 4U
#endif
#ifndef FLAKE_MAX_PENDING_REPLIES
# define FLAKE_MAX_PENDING_REPLIES 10U
#endif
#ifndef FLAKE_MAX_PENDING_INDICATIONS
# define FLAKE_MAX_PENDING_INDICATIONS 10U
#endif
#ifndef FLAKE_MAX_MESSAGE_PAYLOAD
# define FLAKE_MAX_MESSAGE_PAYLOAD 2048U
#endif
/* -----------------------------------------------------------------------
* Size-class byte pool (architectural — variable-length payloads)
*
* Variable-length payloads are served from four fixed buckets.
* @c *_SIZE is one slot's byte width; @c *_COUNT is the slot count for
* that class. @c flakeAlloc hands out the smallest class that fits;
* anything larger than @c FLAKE_POOL_LARGE_SIZE — or arriving when every
* fitting class is busy — falls through to the arena overhang, which is
* bump-allocated and not individually freeable (see @c flake_alloc.h).
*
* These do not derive from @c FLAKE_MAX_OBJECTS / @c FLAKE_MAX_STREAMS:
* streams carry their bytes in the StreamImpl ring buffer (priced by
* @c FLAKE_MAX_STREAMS, not here), and scalar properties (uint/bool/
* int64/float) use only their 52 B Property slot. Only variable-length
* property *values* (strings, blobs, arrays) plus a few internal
* containers (the Message reassembly buffer @c m_payloadBuf, the
* router / UDP-server-wire maps) draw from these buckets.
*
* Sizing keys on the integrator's data, in two populations:
*
* bytepool ≈ Σ resident var-length property values (each rounded up
* to its bucket) [durable]
* + FLAKE_MAX_MESSAGES × largest serialized payload [in-flight]
*
* In transit a value may be held twice (structured in the Property pool
* + serialized in @c m_payloadBuf), so the in-flight term is an upper
* bound. Pick the four @c *_SIZE classes to bracket the value-size
* distribution and each @c *_COUNT for the simultaneously-live count of
* that class. Confirm against a representative run via @c flakePoolStats()
* (peak vs. capacity) and size with margin. The defaults below are
* host-oriented; an MCU client typically cuts MEDIUM/LARGE hard (see the
* override example after the bucket defaults).
* ----------------------------------------------------------------------- */
#ifndef FLAKE_POOL_TINY_SIZE
# define FLAKE_POOL_TINY_SIZE 32U
#endif
#ifndef FLAKE_POOL_TINY_COUNT
# define FLAKE_POOL_TINY_COUNT 16U
#endif
#ifndef FLAKE_POOL_SMALL_SIZE
# define FLAKE_POOL_SMALL_SIZE 128U
#endif
#ifndef FLAKE_POOL_SMALL_COUNT
# define FLAKE_POOL_SMALL_COUNT 16U
#endif
#ifndef FLAKE_POOL_MEDIUM_SIZE
# define FLAKE_POOL_MEDIUM_SIZE 512U
#endif
#ifndef FLAKE_POOL_MEDIUM_COUNT
# define FLAKE_POOL_MEDIUM_COUNT 8U
#endif
#ifndef FLAKE_POOL_LARGE_SIZE
# define FLAKE_POOL_LARGE_SIZE 2048U
#endif
#ifndef FLAKE_POOL_LARGE_COUNT
# define FLAKE_POOL_LARGE_COUNT 8U
#endif
/* Example override for a tight MCU client whose property values are
* short strings + scalars with only occasional larger payloads. Set on
* the compile line or in a pre-include header (anything reached before
* this file picks up the @c #ifndef) — or just build with
* @c -DFLAKE_PROFILE=mcu, which applies the same counts:
*
* -DFLAKE_POOL_SMALL_COUNT=8 -DFLAKE_POOL_MEDIUM_COUNT=2 \
* -DFLAKE_POOL_LARGE_COUNT=1
*
* Byte-pool footprint then drops from ~23 KiB to ~4.5 KiB. Each count
* must stay >= 1 (the @c SlotCount static_assert in @c flake_alloc.cpp).
* To bracket the value-size distribution from a declared data model
* instead of by hand, derive the counts with @c <FlakeSizing.h>, then
* confirm against @c flakePoolStats() peaks on a representative run. */
/* =======================================================================
* SECTION 3 — Derived caps
*
* Defaults computed from sections 1 and 2. Each is @c #ifndef-guarded
* so an integrator can still override for unusual topologies.
* ======================================================================= */
#ifndef FLAKE_MAX_WIRES
/* @c UL suffix on the literal forces the multiplication into
* @c unsigned @c long (≥ size_t on every supported platform), which
* silences clang-tidy's
* @c bugprone-implicit-widening-of-multiplication-result whenever
* this macro participates in a sizeof / array-bound context. The
* preprocessor accepts @c UL natively, so validation @c #if checks
* still work. */
# define FLAKE_MAX_WIRES (2UL * FLAKE_MAX_CONNECTIONS)
#endif
#ifndef FLAKE_MAX_STREAMS
/* @c UL widening as for FLAKE_MAX_WIRES. */
# define FLAKE_MAX_STREAMS (1UL * FLAKE_MAX_STREAMS_PER_OBJECT * FLAKE_MAX_OBJECTS)
#endif
#ifndef FLAKE_MAX_MESSAGES
# define FLAKE_MAX_MESSAGES \
((FLAKE_MAX_CONNECTIONS * \
(FLAKE_MAX_PENDING_REPLIES + FLAKE_MAX_PENDING_INDICATIONS)) / 2U)
#endif
#ifndef FLAKE_MAX_PROPARRAYS
# define FLAKE_MAX_PROPARRAYS \
(((2U + FLAKE_DEFERRED_SLOTS) * FLAKE_MAX_OBJECTS) + FLAKE_MAX_MESSAGES + 16U)
#endif
/* Note: the deferred buffer's per-object data-point budget is
* @c FLAKE_MAX_PROPERTIES; once it is exceeded, @c defer() FIFO-drops the
* oldest snapshot. Across all objects, @c defer() stops taking slots at
* @c FLAKE_DEFERRED_POOL_RESERVE free slots. With multiple offline objects
* the first one to reach that floor dominates; the others keep their
* changes dirty in the store until the pool drains. */
#ifndef FLAKE_MAX_DIRECTORY_ENTRIES
/* @c UL widening as for FLAKE_MAX_WIRES; see comment there. */
# define FLAKE_MAX_DIRECTORY_ENTRIES (4UL * FLAKE_MAX_OBJECTS)
#endif
/* -----------------------------------------------------------------------
* Arena sizing
*
* libflake's runtime storage is drawn from a single @c Arena — either one
* the integrator supplies via @c flakeSetArena, or the library's
* internal default static buffer.
*
* The arena is carved into three layers at init time:
* 1. Per-class @c PoolAllocator<T,N> backing stores (Message, Stream,
* Object, Connection, Router, ServersideObject) plus the shared
* @c WirePool / @c ServerWirePool slices. Wire subclasses share one
* pool (slot size = @c max(sizeof(SubT))) — see @c WirePool.cpp.
* 2. Size-class byte-bucket slots (TINY/SMALL/MEDIUM/LARGE). Bytes are
* exactly @c FLAKE_ARENA_BYTEPOOL_BYTES below.
* 3. Overhang — the rest, used for variable-length allocations that do
* not fit any pool.
*
* The default static buffer in @c arena_globals.cpp is sized exactly via
* @c sizeof of every pooled type at compile time (the file knows every
* pool participant). The @c FLAKE_ARENA_SIZE macro below is a separate
* preprocessor-level upper bound — it exists for integrators who want a
* compile-time constant for their own buffer (the macro can't see
* @c sizeof). The macro carries conservative per-class ceilings; a
* @c static_assert in @c arena_globals.cpp verifies it stays @c >= the
* exact need so integrator-supplied buffers sized by it always fit.
* ----------------------------------------------------------------------- */
#define FLAKE_ARENA_BYTEPOOL_BYTES \
(static_cast<std::size_t>(FLAKE_POOL_TINY_SIZE) * FLAKE_POOL_TINY_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_SMALL_SIZE) * FLAKE_POOL_SMALL_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_MEDIUM_SIZE) * FLAKE_POOL_MEDIUM_COUNT + \
static_cast<std::size_t>(FLAKE_POOL_LARGE_SIZE) * FLAKE_POOL_LARGE_COUNT)
/* @c FLAKE_ARENA_SIZE is defined in @c src/utils/FlakeArenaSize.h, which
* needs the internal type definitions and is therefore neither included by
* @c <flake.h> nor installed with @c src/inc/. Include it explicitly as
* @c <utils/FlakeArenaSize.h> with @c src/ on the include path. */
/* =======================================================================
* SECTION 4 — Validation
*
* Every invariant either the library's source code or the derivations
* above rely on is checked here. Triggered when an integrator overrides
* one of the derived caps (or a constant) such that an invariant
* breaks; the build fails at preprocess time rather than at runtime.
* ======================================================================= */
#if FLAKE_MAX_CONNECTIONS < 1U
# error "FLAKE_MAX_CONNECTIONS must be >= 1"
#endif
#if FLAKE_MAX_OBJECTS < 1U
# error "FLAKE_MAX_OBJECTS must be >= 1"
#endif
#if FLAKE_MAX_PROPERTIES < 1U
# error "FLAKE_MAX_PROPERTIES must be >= 1"
#endif
#if FLAKE_DEFERRED_POOL_RESERVE >= FLAKE_MAX_PROPERTIES
# error "FLAKE_DEFERRED_POOL_RESERVE must leave defer() part of the pool"
#endif
/* Wire pool must accommodate in-process router (2 IPCWires per
* connection). Tighter values are valid only on pure-client builds
* that do not host a router in the same process. */
#if FLAKE_MAX_WIRES < (2U * FLAKE_MAX_CONNECTIONS)
# warning "FLAKE_MAX_WIRES < 2 * FLAKE_MAX_CONNECTIONS — in-process router will exhaust wires"
#endif
/* Streams pool must hold the worst case (every object opens its
* full per-object quota). Anything less is an under-estimate. */
#if FLAKE_MAX_STREAMS < (FLAKE_MAX_STREAMS_PER_OBJECT * FLAKE_MAX_OBJECTS)
# error "FLAKE_MAX_STREAMS too small (must be >= FLAKE_MAX_STREAMS_PER_OBJECT * FLAKE_MAX_OBJECTS)"
#endif
/* PropArray registry must fit the concrete demand: 2 + FLAKE_DEFERRED_SLOTS
* PropArrays per ObjectImpl (properties + cache + deferred slots) plus 1
* per Message in flight. */
#if FLAKE_MAX_PROPARRAYS < (((2U + FLAKE_DEFERRED_SLOTS) * FLAKE_MAX_OBJECTS) + FLAKE_MAX_MESSAGES)
# error "FLAKE_MAX_PROPARRAYS too small (need (2 + FLAKE_DEFERRED_SLOTS) * FLAKE_MAX_OBJECTS + FLAKE_MAX_MESSAGES)"
#endif
#if FLAKE_DEFERRED_SLOTS < 1U
# error "FLAKE_DEFERRED_SLOTS must be >= 1"
#endif
#if (FLAKE_DEFERRED_OFFSET_ENTRIES < 1U) || (FLAKE_DEFERRED_OFFSET_ENTRIES > 255U)
# error "FLAKE_DEFERRED_OFFSET_ENTRIES must be in 1..255"
#endif
#if FLAKE_DEFERRED_OFFSET_TABLES < 1U
# error "FLAKE_DEFERRED_OFFSET_TABLES must be >= 1"
#endif
#endif /* FLAKE_LIMITS_H */