Skip to content

file FlakeLimits.h ​

Defines ​

Name
FLAKE_MAX_CONNECTIONSMaximum number of concurrent client Connection instances.
FLAKE_MAX_OBJECTSMaximum number of cached ObjectImpl / ServersideObject instances per side of the protocol.
FLAKE_MAX_PROPERTIESTotal number of Property slots the shared PropertyPool can hold across the entire process.
FLAKE_DEFERRED_SLOTSDeferred snapshots (slots) per object.
FLAKE_DEFERRED_POOL_RESERVEProperty slots defer() leaves to everything else in the pool.
FLAKE_DEFERRED_OFFSET_ENTRIESPer-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_TABLESOffset tables shared by all objects.
FLAKE_REPORT_BUFFER_BYTESFixed report storage for value history, in bytes; 0 keeps the history buffers in the shared byte pool.
FLAKE_MAX_PRIO_RANGESTag ranges per object for Object::setPriority and Object::setHistoryClass, each.
FLAKE_MAX_PEER_SESSIONSStreams 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_ROUTERSMaximum number of concurrent Router instances in a process.
FLAKE_MAX_STREAMS_PER_OBJECTMaximum number of open Stream objects per ObjectImpl.
FLAKE_MAX_SERVER_WIRESTotal cap on live ServerWire instances in the process.
FLAKE_MAX_PENDING_REPLIESMaximum 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_INDICATIONSMaximum number of outstanding indication tokens per Transport. Bounds how many in-flight indications one Transport tracks.
FLAKE_MAX_MESSAGE_PAYLOADMaximum 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_SIZELarge bucket: slot width and count.
FLAKE_POOL_LARGE_COUNT
FLAKE_MAX_WIRESTotal cap on live Wire instances in the process.
FLAKE_MAX_STREAMSTotal maximum of live StreamImpl instances across all objects. Derived from the per-object Stream cap and the object pool.
FLAKE_MAX_MESSAGESMaximum number of Flake protocol Message objects in flight across the whole process.
FLAKE_MAX_PROPARRAYSMaximum number of live PropArray instances registered with the shared PropertyPool.
FLAKE_MAX_DIRECTORY_ENTRIESMaximum number of entries in an ObjectTree's directory.
FLAKE_ARENA_BYTEPOOL_BYTESExact total bytes the size-class byte buckets will need.

Macros Documentation ​

define FLAKE_MAX_CONNECTIONS ​

cpp
#define FLAKE_MAX_CONNECTIONS 4U

Maximum 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 8U

Maximum 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 256U

Total 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 3U

Deferred 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 64U

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.

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 0U

Fixed 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 8U

Tag 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_OBJECT

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.

define FLAKE_MAX_ROUTERS ​

cpp
#define FLAKE_MAX_ROUTERS 1U

Maximum 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 2U

Maximum 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 4U

Total 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 10U

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.

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 10U

Maximum 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 2048U

Maximum 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 32U

define FLAKE_POOL_TINY_COUNT ​

cpp
#define FLAKE_POOL_TINY_COUNT 16U

define FLAKE_POOL_SMALL_SIZE ​

cpp
#define FLAKE_POOL_SMALL_SIZE 128U

define FLAKE_POOL_SMALL_COUNT ​

cpp
#define FLAKE_POOL_SMALL_COUNT 16U

define FLAKE_POOL_MEDIUM_SIZE ​

cpp
#define FLAKE_POOL_MEDIUM_SIZE 512U

define FLAKE_POOL_MEDIUM_COUNT ​

cpp
#define FLAKE_POOL_MEDIUM_COUNT 8U

define FLAKE_POOL_LARGE_SIZE ​

cpp
#define FLAKE_POOL_LARGE_SIZE 2048U

Large 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 8U

define 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 */