Skip to content

file FlakeConst.h ​

Defines ​

Name
FLAKE_DEBUG_LOGGINGEnable / disable verbose debug logging (1 = on, 0 = off).
FLAKE_LOG_LINE_BUF_BYTESStack-buffer size for one formatted log line. Lines longer than this get truncated. Sized for typical diagnostic output; lower it on tight stack budgets.
FLAKE_REF_DEBUGEnable / disable Ref ref/unref source-location tracking (1 = on, 0 = off). When off, the std::source_location parameter is dropped from ref()/unref() entirely so that no file/function string is materialised at call sites in release builds.
FLAKE_REFLOC_DECL
FLAKE_REFLOC_PARAM
FLAKE_REFLOC_FWD
FLAKE_AUTH_SUPPORTEnable / disable authentication support (1 = on, 0 = off).
FLAKE_TLSEnable / disable TLS transport (1 = on, 0 = off).
FLAKE_DTLSEnable / disable DTLS transport (1 = on, 0 = off).
FLAKE_STREAM_TIMEOUT_MSInactivity after which a stream a peer opened on a local object is closed, in milliseconds; 0 = never.
FLAKE_DEFAULT_TIMEOUT_MSDefault timeout for general request/reply operations, in milliseconds.
FLAKE_CONNECTION_WAIT_LIMIT_TICKSMaintenance ticks a router-side ServerConnection may stay in the not-yet-connected() state before being torn down as stale.
FLAKE_CLIENT_PING_IDLE_MSIdle window after which a connected client probes the router with a ping, in milliseconds. 0 disables the probe.
FLAKE_CLIENT_PING_RETRY_LIMITUnanswered client probes tolerated before the session is dropped.
FLAKE_PROBE_AUTOProbe window value for flakeSetLivenessProbe that follows the contact interval the router confirmed, plus FLAKE_PROBE_AUTO_GRACE_MS. Without a confirmation the window stays at FLAKE_CLIENT_PING_IDLE_MS.
FLAKE_PROBE_AUTO_GRACE_MSMargin on top of the confirmed contact interval in FLAKE_PROBE_AUTO mode. The device's own report is due at the interval; the margin keeps the probe from firing just before it.
FLAKE_CLIENT_DROP_ON_NOT_CONNECTEDDrop the session when the router answers a request of this client with E_NOT_CONNECTED. 0 leaves it to the integration.
FLAKE_PEER_STREAM_IDLE_MSIdle time after which a stream the peer opened on a local object no longer counts as an open peer session, in milliseconds; 0 = never.
MAX_PENDING_REPLIESMaximum number of pending (not yet answered) request replies.
MAX_PENDING_INDICATIONSMaximum number of pending indications.
FLAKE_SUCCEEDED(e)Test whether an error code represents a logical success.

Macros Documentation ​

define FLAKE_DEBUG_LOGGING ​

cpp
#define FLAKE_DEBUG_LOGGING 1

Enable / disable verbose debug logging (1 = on, 0 = off).

define FLAKE_LOG_LINE_BUF_BYTES ​

cpp
#define FLAKE_LOG_LINE_BUF_BYTES 512U

Stack-buffer size for one formatted log line. Lines longer than this get truncated. Sized for typical diagnostic output; lower it on tight stack budgets.

define FLAKE_REF_DEBUG ​

cpp
#define FLAKE_REF_DEBUG 0

Enable / disable Ref ref/unref source-location tracking (1 = on, 0 = off). When off, the std::source_location parameter is dropped from ref()/unref() entirely so that no file/function string is materialised at call sites in release builds.

define FLAKE_REFLOC_DECL ​

cpp
#define FLAKE_REFLOC_DECL

define FLAKE_REFLOC_PARAM ​

cpp
#define FLAKE_REFLOC_PARAM

define FLAKE_REFLOC_FWD ​

cpp
#define FLAKE_REFLOC_FWD

define FLAKE_AUTH_SUPPORT ​

cpp
#define FLAKE_AUTH_SUPPORT 1

Enable / disable authentication support (1 = on, 0 = off).

define FLAKE_TLS ​

cpp
#define FLAKE_TLS 0

Enable / disable TLS transport (1 = on, 0 = off).

define FLAKE_DTLS ​

cpp
#define FLAKE_DTLS 0

Enable / disable DTLS transport (1 = on, 0 = off).

define FLAKE_STREAM_TIMEOUT_MS ​

cpp
#define FLAKE_STREAM_TIMEOUT_MS 30000U

Inactivity after which a stream a peer opened on a local object is closed, in milliseconds; 0 = never.

Each such stream holds one of the object's FLAKE_MAX_STREAMS_PER_OBJECT slots until it is closed, also after its peer is gone. Without a read, write or seek from a peer for this long the owner closes it as if the application had: the peer sessions on it end, ObjectDelegate::handleStreamClose is called and the stream is released. The peer is not told; its next request on the stream fails. Streams the application opened are left alone. Adjustable at runtime with flakeSetStreamTimeoutMs.

define FLAKE_DEFAULT_TIMEOUT_MS ​

cpp
#define FLAKE_DEFAULT_TIMEOUT_MS 10000U

Default timeout for general request/reply operations, in milliseconds.

define FLAKE_CONNECTION_WAIT_LIMIT_TICKS ​

cpp
#define FLAKE_CONNECTION_WAIT_LIMIT_TICKS 30

Maintenance ticks a router-side ServerConnection may stay in the not-yet-connected() state before being torn down as stale.

One tick equals one Router::checkConnections() pass, which fires at most every FLAKE_DEFAULT_TIMEOUT_MS. Default of 30 ticks gives a fresh wire ~5 minutes to complete its connect handshake — generous on production, but the budget exists primarily to absorb mutation-test (Mull) and sanitiser slowdowns, where a threshold of 3 (~30 s) trips on slow handshakes.

define FLAKE_CLIENT_PING_IDLE_MS ​

cpp
#define FLAKE_CLIENT_PING_IDLE_MS (5U * 60U * 1000U)

Idle window after which a connected client probes the router with a ping, in milliseconds. 0 disables the probe.

The router-side keepalive (ServerConnection::ping) only tells the router whether a client is still there. Nothing told the client that its session had died: on a datagram wire there is no connection to lose, and a [sendto()](/embed/2.2.0/API//group__tcpip.md#function-sendto) into a dead return path succeeds locally, so the client kept a session that no longer existed and the layers above it were never informed. Field symptom: a share of the devices stopped reaching the backend and only came back after a power cycle.

The probe is a ping with Destination 0x0000, which the protocol defines as answered by the router with E_OK. The window is measured over received traffic only, for the reason above; any message from the router, the ping answer included, closes it. After FLAKE_CLIENT_PING_RETRY_LIMIT unanswered probes, spaced FLAKE_DEFAULT_TIMEOUT_MS apart, the transport is torn down so the integration learns of it through ConnectionSink::onDisconnected and can rebuild.

Five minutes stays quiet only as long as the router pings its clients more often than that and so closes the window on its own. A device that announces a longer contact interval (flakeSetContactInterval) to a router that no longer pings turns the probe into a keepalive; such integrations set the window at runtime with flakeSetLivenessProbe, usually to FLAKE_PROBE_AUTO or 0. Worst-case detection latency is the window plus FLAKE_CLIENT_PING_RETRY_LIMIT * FLAKE_DEFAULT_TIMEOUT_MS.

define FLAKE_CLIENT_PING_RETRY_LIMIT ​

cpp
#define FLAKE_CLIENT_PING_RETRY_LIMIT 3U

Unanswered client probes tolerated before the session is dropped.

Mirrors the router's own ping budget in Router::checkConnections.

define FLAKE_PROBE_AUTO ​

cpp
#define FLAKE_PROBE_AUTO 0xFFFFFFFFU

Probe window value for flakeSetLivenessProbe that follows the contact interval the router confirmed, plus FLAKE_PROBE_AUTO_GRACE_MS. Without a confirmation the window stays at FLAKE_CLIENT_PING_IDLE_MS.

define FLAKE_PROBE_AUTO_GRACE_MS ​

cpp
#define FLAKE_PROBE_AUTO_GRACE_MS (60U * 1000U)

Margin on top of the confirmed contact interval in FLAKE_PROBE_AUTO mode. The device's own report is due at the interval; the margin keeps the probe from firing just before it.

define FLAKE_CLIENT_DROP_ON_NOT_CONNECTED ​

cpp
#define FLAKE_CLIENT_DROP_ON_NOT_CONNECTED 1

Drop the session when the router answers a request of this client with E_NOT_CONNECTED. 0 leaves it to the integration.

A router answers that way when it no longer knows the sender, typically after it restarted or expired the session. Every further request on the session fails the same way, so waiting for an error series only adds traffic before the inevitable rebuild. Only answers whose source is the router itself (0x0000) or one of this client's own objects count; an answer forwarded from another peer says nothing about this session.

define FLAKE_PEER_STREAM_IDLE_MS ​

cpp
#define FLAKE_PEER_STREAM_IDLE_MS 0U

Idle time after which a stream the peer opened on a local object no longer counts as an open peer session, in milliseconds; 0 = never.

A peer that vanishes without closing (the backend drops a viewer, the session dies) would otherwise keep the session counted forever, and with it whatever the integration does while a peer is watching. Any read, write or seek on the stream restarts the idle time. Adjustable at runtime with flakeSetPeerStreamIdleMs.

define MAX_PENDING_REPLIES ​

cpp
#define MAX_PENDING_REPLIES 10U

Maximum number of pending (not yet answered) request replies.

define MAX_PENDING_INDICATIONS ​

cpp
#define MAX_PENDING_INDICATIONS 10U

Maximum number of pending indications.

Note: Should be proportional to the number of concurrent TCP connections.

define FLAKE_SUCCEEDED ​

cpp
#define FLAKE_SUCCEEDED(
    e
)
({ int result = (e); result == E_OK || result == E_READ_ONLY || result == E_NO_CHANGES; })

Test whether an error code represents a logical success.

Parameters:

  • e Expression that evaluates to an int error code.

Return: true if the code is a success value, false otherwise.

The following codes are treated as "succeeded": E_OK, E_READ_ONLY, E_NO_CHANGES.

Source code ​

cpp
/*******************************************************************************
 * @file      FlakeConst.h
 * @brief     Compile-time configuration switches, default timeouts, and
 *            library-wide error / status codes.
 * @details   Every macro in this file can be overridden by defining the value
 *            before this header is included (or via compiler flags) unless
 *            stated otherwise.
 *
 * @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_CONST_H_
#define FLAKE_CONST_H_

/* -----------------------------------------------------------------------
 *  Build-time feature switches
 * ----------------------------------------------------------------------- */

#ifndef FLAKE_DEBUG_LOGGING
#define FLAKE_DEBUG_LOGGING             1
#endif

#ifndef FLAKE_LOG_LINE_BUF_BYTES
#define FLAKE_LOG_LINE_BUF_BYTES        512U
#endif

#ifndef FLAKE_REF_DEBUG
#define FLAKE_REF_DEBUG                 0
#endif

#if FLAKE_REF_DEBUG
#  include <source_location>
#  define FLAKE_REFLOC_DECL  std::source_location loc = std::source_location::current()
#  define FLAKE_REFLOC_PARAM std::source_location loc
#  define FLAKE_REFLOC_FWD   loc
#else
#  define FLAKE_REFLOC_DECL
#  define FLAKE_REFLOC_PARAM
#  define FLAKE_REFLOC_FWD
#endif

#ifndef FLAKE_AUTH_SUPPORT
#define FLAKE_AUTH_SUPPORT              1
#endif

#ifndef FLAKE_TLS
#define FLAKE_TLS                       0
#endif

#ifndef FLAKE_DTLS
#define FLAKE_DTLS                      0
#endif

/* -----------------------------------------------------------------------
 *  Default timeout values
 * ----------------------------------------------------------------------- */

#ifndef FLAKE_STREAM_TIMEOUT_MS
#define FLAKE_STREAM_TIMEOUT_MS          30000U
#endif

#ifndef FLAKE_DEFAULT_TIMEOUT_MS
#define FLAKE_DEFAULT_TIMEOUT_MS         10000U
#endif

#ifndef FLAKE_CONNECTION_WAIT_LIMIT_TICKS
#define FLAKE_CONNECTION_WAIT_LIMIT_TICKS  30
#endif

#ifndef FLAKE_CLIENT_PING_IDLE_MS
#define FLAKE_CLIENT_PING_IDLE_MS        (5U * 60U * 1000U)
#endif

#ifndef FLAKE_CLIENT_PING_RETRY_LIMIT
#define FLAKE_CLIENT_PING_RETRY_LIMIT    3U
#endif

#define FLAKE_PROBE_AUTO                 0xFFFFFFFFU

#ifndef FLAKE_PROBE_AUTO_GRACE_MS
#define FLAKE_PROBE_AUTO_GRACE_MS        (60U * 1000U)
#endif

#ifndef FLAKE_CLIENT_DROP_ON_NOT_CONNECTED
#define FLAKE_CLIENT_DROP_ON_NOT_CONNECTED 1
#endif

#ifndef FLAKE_PEER_STREAM_IDLE_MS
#define FLAKE_PEER_STREAM_IDLE_MS        0U
#endif

/* -----------------------------------------------------------------------
 *  Internal queue limits
 * ----------------------------------------------------------------------- */

#define MAX_PENDING_REPLIES              10U

#define MAX_PENDING_INDICATIONS          10U

/* -----------------------------------------------------------------------
 *  Error / status codes
 * ----------------------------------------------------------------------- */

#define E_OK                             (0)    
#define E_FAILED                         (-1)   
#define E_NO_ALLOC                       (-2)   
#define E_NOT_FOUND                      (-3)   
#define E_READ_ONLY                      (-4)   
#define E_NOT_IMPL                       (-5)   
#define E_PENDING                        (-6)   
#define E_OBJECT_NOT_INITIALIZED         (-7)   
#define E_UNREGISTERED_OBJECT            (-8)   
#define E_IGNORED                        (-9)   
#define E_NO_CHANGES                     (-10)  
#define E_PARTIAL_SUCCESS                (-11)  
#define E_INCOMPLETE                     (-12)  
#define E_UNSUPPORTED                    (-13)  
#define E_UNAUTHORIZED                   (-14)  
#define E_EOF                            (-15)  
#define E_BUSY                           (-16)  
#define E_DOUBLE_RELEASE                 (-17)  
#define E_TIMEOUT                        (-101) 
#define E_NOT_CONNECTED                  (-102) 
#define E_REFUSED                        (-103) 
#define E_DONT_DISPATCH                  (-104) 
#define E_DESTINATION_UNREACHABLE        (-105) 
#define E_INVALID_PARAM                  (-106) 
#define E_FCNTL                          (-1000) 
#define E_LISTEN                         (-1001) 
#define E_SOCK                           (-1002) 
#define E_BIND                           (-1003) 
 /* end of flake_error_codes */
#define FLAKE_SUCCEEDED(e)  ({ int result = (e); result == E_OK || result == E_READ_ONLY || result == E_NO_CHANGES; })

#endif /* FLAKE_CONST_H_ */