Appearance
file FlakeConst.h
Defines
| Name | |
|---|---|
| FLAKE_DEBUG_LOGGING | Enable / disable verbose debug logging (1 = on, 0 = off). |
| FLAKE_LOG_LINE_BUF_BYTES | 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. |
| FLAKE_REF_DEBUG | 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. |
| FLAKE_REFLOC_DECL | |
| FLAKE_REFLOC_PARAM | |
| FLAKE_REFLOC_FWD | |
| FLAKE_AUTH_SUPPORT | Enable / disable authentication support (1 = on, 0 = off). |
| FLAKE_TLS | Enable / disable TLS transport (1 = on, 0 = off). |
| FLAKE_DTLS | Enable / disable DTLS transport (1 = on, 0 = off). |
| FLAKE_STREAM_TIMEOUT_MS | Inactivity after which a stream a peer opened on a local object is closed, in milliseconds; 0 = never. |
| FLAKE_DEFAULT_TIMEOUT_MS | Default timeout for general request/reply operations, in milliseconds. |
| FLAKE_CONNECTION_WAIT_LIMIT_TICKS | Maintenance ticks a router-side ServerConnection may stay in the not-yet-connected() state before being torn down as stale. |
| FLAKE_CLIENT_PING_IDLE_MS | Idle window after which a connected client probes the router with a ping, in milliseconds. 0 disables the probe. |
| FLAKE_CLIENT_PING_RETRY_LIMIT | Unanswered client probes tolerated before the session is dropped. |
| FLAKE_PROBE_AUTO | 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. |
| FLAKE_PROBE_AUTO_GRACE_MS | 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. |
| FLAKE_CLIENT_DROP_ON_NOT_CONNECTED | Drop 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_MS | 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. |
| MAX_PENDING_REPLIES | Maximum number of pending (not yet answered) request replies. |
| MAX_PENDING_INDICATIONS | Maximum 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 1Enable / disable verbose debug logging (1 = on, 0 = off).
define FLAKE_LOG_LINE_BUF_BYTES
cpp
#define FLAKE_LOG_LINE_BUF_BYTES 512UStack-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 0Enable / 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_DECLdefine FLAKE_REFLOC_PARAM
cpp
#define FLAKE_REFLOC_PARAMdefine FLAKE_REFLOC_FWD
cpp
#define FLAKE_REFLOC_FWDdefine FLAKE_AUTH_SUPPORT
cpp
#define FLAKE_AUTH_SUPPORT 1Enable / disable authentication support (1 = on, 0 = off).
define FLAKE_TLS
cpp
#define FLAKE_TLS 0Enable / disable TLS transport (1 = on, 0 = off).
define FLAKE_DTLS
cpp
#define FLAKE_DTLS 0Enable / disable DTLS transport (1 = on, 0 = off).
define FLAKE_STREAM_TIMEOUT_MS
cpp
#define FLAKE_STREAM_TIMEOUT_MS 30000UInactivity 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 10000UDefault timeout for general request/reply operations, in milliseconds.
define FLAKE_CONNECTION_WAIT_LIMIT_TICKS
cpp
#define FLAKE_CONNECTION_WAIT_LIMIT_TICKS 30Maintenance 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 3UUnanswered 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 0xFFFFFFFFUProbe 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 1Drop 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 0UIdle 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 10UMaximum number of pending (not yet answered) request replies.
define MAX_PENDING_INDICATIONS
cpp
#define MAX_PENDING_INDICATIONS 10UMaximum 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
interror 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_ */