Appearance
class flake::Object
Client-side proxy for a Flake object. More...
#include <platform/flake/Object.h>
Public Functions
| Name | |
|---|---|
| Object(const Object & ) =deleted | |
| Object & | operator=(const Object & ) =deleted |
| Object(Object && ) =deleted | |
| Object & | operator=(Object && ) =deleted |
| virtual int | registered() =0 Check whether the object is registered with the router. |
| virtual int | invoke(const char * command, PropArray & params, bool blocking, PropArray & reply) =0 Invoke a named custom function on the object. |
| virtual int | broadcast(const char * command, PropArray & params) =0 Broadcast a named custom message to all subscribers. |
| virtual int | getProperties(PropArray & properties) =0 Retrieve all properties of the object. |
| virtual int | setProperties(PropArray & properties) =0 Set multiple properties on the object in one call. |
| virtual int | setProperty(const Property & property) =0 Set a single property on the object. |
| virtual void | getProperty(Property & property) =0 Read a single property from the local cache. |
| virtual int | openProperty(const uint32_t propTag, Stream ** stream) =0 Open a stream associated with a stream-typed property. |
| virtual int | subscribe(std::function< void(const Indication &)> f) =0 Subscribe to property-change notifications. |
| virtual void | unsubscribe() =0 Remove all subscriptions from this object. |
| virtual int | sync(unsigned timeout_ms, bool block) =0 Flush pending local property changes to the router. |
| virtual void | defer() =0 Move all pending local property changes into a deferred buffer instead of syncing immediately. |
| virtual int | syncDeferred(unsigned timeout_ms, bool block) =0 Flush all deferred property changes to the router. |
| virtual bool | hasDeferred() =0 Check whether there are deferred property changes waiting. |
| virtual void | clear() =0 Discard all pending and deferred local property changes. |
| int | setPriority(uint16_t idFirst, uint16_t idLast, uint8_t prio) Assign a priority to the tag IDs idFirst..idLast. |
| uint8_t | priority(uint32_t tag) Priority of tag; FLAKE_PRIO_NORMAL unless a range of setPriority() covers it. |
| bool | hasUrgentPending() True while a value of priority FLAKE_PRIO_IMMEDIATE is set but not yet confirmed by the router. |
| int | setHistoryClass(uint16_t idFirst, uint16_t idLast, uint8_t cls) Assign a history class to the tag IDs idFirst..idLast. |
| void | setHistoryStage(uint8_t stage) Budget stage the integration has reached (FLAKE_HISTORY_STAGE_NORMAL … FLAKE_HISTORY_STAGE_HOLD). Applies to samples recorded from now on. |
| void | setRecordSamples(bool on) Record every change with its own time. |
| int | flushReport(unsigned timeout_ms) Send everything pending as one report. |
| int | reportFill(ReportFill * out) Report the fill level and loss counters of the pending report. |
| virtual void | ref() =0 Increment the reference count. |
| virtual void | unref() =0 Decrement the reference count. |
Protected Functions
| Name | |
|---|---|
| Object() =default | |
| ~Object() =default | |
| virtual ObjectImpl * | impl() =0 Access the internal implementation. |
Friends
| Name | |
|---|---|
| class | ConnectionImpl |
Detailed Description
cpp
class flake::Object;Client-side proxy for a Flake object.
Note: Non-copyable, non-movable.
Par: Ownership
Every Object obtained from queryObjects() starts with a reference count of 1. Call ref() / unref() to manage the lifetime. When the count reaches zero the Object is returned to the internal pool.
Object instances are obtained from Connection::queryObjects(). They provide property access, remote invocation, subscription, and stream opening.
Public Functions Documentation
function Object
cpp
Object(
const Object &
) =deletedfunction operator=
cpp
Object & operator=(
const Object &
) =deletedfunction Object
cpp
Object(
Object &&
) =deletedfunction operator=
cpp
Object & operator=(
Object &&
) =deletedfunction registered
cpp
virtual int registered() =0Check whether the object is registered with the router.
Return: E_OK if registered, or a negative error code.
function invoke
cpp
virtual int invoke(
const char * command,
PropArray & params,
bool blocking,
PropArray & reply
) =0Invoke a named custom function on the object.
Parameters:
- command Name of the function to invoke.
- params Input parameters as a PropArray.
- blocking If
true, block until the result is received; set tofalsefor fire-and-forget ("void") calls. - reply Output parameters populated by the callee (only meaningful when
blockingistrue).
Return: E_OK on success, or a negative error code.
Custom functions are implementation-defined and not part of any standard device class.
function broadcast
cpp
virtual int broadcast(
const char * command,
PropArray & params
) =0Broadcast a named custom message to all subscribers.
Parameters:
- command Name of the message.
- params Message parameters as a PropArray.
Return: E_OK on success, or a negative error code.
Custom messages are implementation-defined and not part of any standard device class.
function getProperties
cpp
virtual int getProperties(
PropArray & properties
) =0Retrieve all properties of the object.
Parameters:
- properties PropArray that receives the current property values.
Return: E_OK on success, or a negative error code.
function setProperties
cpp
virtual int setProperties(
PropArray & properties
) =0Set multiple properties on the object in one call.
Parameters:
- properties PropArray of properties to set. On return, each property may carry an error tag if it could not be applied.
Return: E_OK on success, or a negative error code.
function setProperty
cpp
virtual int setProperty(
const Property & property
) =0Set a single property on the object.
Parameters:
- property The property to set.
Return: E_OK on success, or a negative error code.
The property is not sent to the router immediately; it is cached locally until sync() or defer() / syncDeferred() is called.
function getProperty
cpp
virtual void getProperty(
Property & property
) =0Read a single property from the local cache.
Parameters:
- property On entry, the tag identifies which property to read. On return, the value is filled in.
If the property has not been fetched yet the returned Property will carry a TAG_NULL flag.
function openProperty
cpp
virtual int openProperty(
const uint32_t propTag,
Stream ** stream
) =0Open a stream associated with a stream-typed property.
Parameters:
- propTag Tag of a
TT_STRING_STREAMorTT_BIN_STREAMproperty. - stream Receives a pointer to the opened Stream.
Return: E_OK on success, or a negative error code.
function subscribe
cpp
virtual int subscribe(
std::function< void(const Indication &)> f
) =0Subscribe to property-change notifications.
Parameters:
- f Callback invoked whenever the object's properties change.
Return: E_OK on success, or a negative error code.
function unsubscribe
cpp
virtual void unsubscribe() =0Remove all subscriptions from this object.
function sync
cpp
virtual int sync(
unsigned timeout_ms,
bool block
) =0Flush pending local property changes to the router.
Parameters:
- timeout_ms Maximum wait time in milliseconds.
- block If
true, wait synchronously for the router's confirmation.
Return: E_OK on success, or a negative error code.
Properties set via setProperty() are batched locally. On a datagram wire sync() first drains every deferred snapshot, one confirmed datagram after the other, and then sends one datagram of the pending values; whatever does not fit the MTU stays pending for the next call. flushReport() sends everything.
Auto-defer on wire failure (datagram only)
On datagram wires (UDP, DTLS) a wire-level failure — timeout, lost confirmation, transient disconnect — automatically re-deposits the in-flight property snapshot into the deferred buffer (as if defer() had been called with the send-attempt timestamp). The next sync() or syncDeferred() picks it up from there, merged with anything that has accumulated in the meantime, so no update is lost across an unreliable link.
Application-level errors returned in the confirmation (E_PARTIAL_SUCCESS, individual property errors, …) do not trigger the auto-defer — they are part of a normally-received confirmation and the caller handles them.
Stream wires (TCP, TLS) do not auto-defer: a wire-level failure there usually means the connection is gone and the reconnect path takes over.
function defer
cpp
virtual void defer() =0Move all pending local property changes into a deferred buffer instead of syncing immediately.
Deferred changes accumulate and can later be flushed with syncDeferred(). Repeated defer() calls fold into the same deferred snapshot: older samples of a property migrate into a history blob, each with its own time. A value only gets its own time when defer() runs after each change (or with setRecordSamples()); two changes between two defer() calls leave only the second. Samples that cannot be kept (storage exhausted, no history encoding for arrays) are counted in reportFill(), never dropped silently.
Pair with a periodic syncDeferred() to amortise IP/UDP/Flake header overhead across many updates — see syncDeferred() for how to pick the period.
function syncDeferred
cpp
virtual int syncDeferred(
unsigned timeout_ms,
bool block
) =0Flush all deferred property changes to the router.
Parameters:
- timeout_ms Maximum wait time in milliseconds.
- block If
true, wait synchronously.
Return: E_OK on success, or a negative error code.
Picking how often to call
Each wire message pays ~85 bytes of fixed overhead (IP+UDP+ Flake header + per-message TIMESTAMP meta), independent of payload size. Batching multiple defer()s into one syncDeferred() trades that overhead off against the additional staleness it introduces. Net savings per merged update are roughly:
savings_per_merge ≈ (85 − 4·N) byteswhere N is the average number of distinct properties per update. For sensor-style traffic (small N) batching is very effective; once N approaches 20+ the per-property offset bookkeeping eats the savings and immediate sync() is just as cheap.
A useful rule of thumb for the sync period T given a sensor rate of λ updates/s:
T ≈ min(L_max, ~11/λ)where L_max is the maximum staleness the consumer tolerates. The 11/λ term captures ~90% of the achievable savings; going much beyond that saturates. Examples:
1 Hz sensor, 2 s staleness OK → T = 2 s (~60% saved)
1 Hz sensor, 10 s staleness OK → T = 10 s (~85% saved)10 Hz sensor, 1 s staleness OK → T = 1 s (~85% saved)
For one-off / non-streaming updates, just use sync() — there is nothing to batch.
function hasDeferred
cpp
virtual bool hasDeferred() =0Check whether there are deferred property changes waiting.
Return: true if deferred data exists, false otherwise.
function clear
cpp
virtual void clear() =0Discard all pending and deferred local property changes.
function setPriority
cpp
int setPriority(
uint16_t idFirst,
uint16_t idLast,
uint8_t prio
)Assign a priority to the tag IDs idFirst..idLast.
Return: E_OK, E_NO_ALLOC when FLAKE_MAX_PRIO_RANGES ranges are set, E_INVALID_PARAM for an empty range.
A value of priority FLAKE_PRIO_IMMEDIATE notifies ObjectDelegate::onUrgentPending() when it becomes pending and is placed in the first datagram of the next sync() or flushReport(). Ranges set later win over earlier ones. Purely local; nothing of it goes on the wire.
function priority
cpp
uint8_t priority(
uint32_t tag
)Priority of tag; FLAKE_PRIO_NORMAL unless a range of setPriority() covers it.
function hasUrgentPending
cpp
bool hasUrgentPending()True while a value of priority FLAKE_PRIO_IMMEDIATE is set but not yet confirmed by the router.
function setHistoryClass
cpp
int setHistoryClass(
uint16_t idFirst,
uint16_t idLast,
uint8_t cls
)Assign a history class to the tag IDs idFirst..idLast.
Return: E_OK, E_NO_ALLOC when FLAKE_MAX_PRIO_RANGES ranges are set, E_INVALID_PARAM otherwise.
FLAKE_HISTORY_COMPLETE, FLAKE_HISTORY_CONDENSABLE (default) or FLAKE_HISTORY_LATEST. Takes effect through setHistoryStage(); at FLAKE_HISTORY_STAGE_NORMAL every sample is kept. When the report storage is full, samples of LATEST tags give way first, then CONDENSABLE ones, never COMPLETE ones.
function setHistoryStage
cpp
void setHistoryStage(
uint8_t stage
)Budget stage the integration has reached (FLAKE_HISTORY_STAGE_NORMAL … FLAKE_HISTORY_STAGE_HOLD). Applies to samples recorded from now on.
function setRecordSamples
cpp
void setRecordSamples(
bool on
)Record every change with its own time.
With on, every setProperty()/setProperties() that changes a value moves it into the deferred snapshot at once, as if defer() had been called right after it; the previous value goes into the history with its time. The application then no longer calls defer(). No effect on stream wires, which never defer.
function flushReport
cpp
int flushReport(
unsigned timeout_ms
)Send everything pending as one report.
Parameters:
- timeout_ms Timeout per part.
Return: E_OK when every part was confirmed, E_NO_CHANGES when nothing was pending, otherwise the error of the part that failed. On a stream wire this is sync(timeout_ms, true).
Moves the pending values into the deferred snapshot and drains all snapshots in as many datagrams as needed, one confirmed part after the other. Values of priority FLAKE_PRIO_IMMEDIATE go in the first datagram. Each confirmed part stays delivered if a later one fails; the rest waits for the next call.
function reportFill
cpp
int reportFill(
ReportFill * out
)Report the fill level and loss counters of the pending report.
Parameters:
- out Filled on success.
Return: E_OK, or E_INVALID_PARAM for a null out.
function ref
cpp
virtual void ref() =0Increment the reference count.
Every ref() must be balanced by a corresponding unref(). When the library is built with FLAKE_REF_DEBUG, the call site is captured via std::source_location and logged alongside the new counter so leaks can be traced back to the originating call. In release builds the parameter is absent entirely — no file/function string is materialised at call sites.
function unref
cpp
virtual void unref() =0Decrement the reference count.
When the count reaches zero the object is destroyed / returned to the pool. See [ref()](/embed/2.2.0/API/Classes/classflake_1_1Object.md#function-ref) for the optional loc parameter.
Protected Functions Documentation
function Object
cpp
Object() =defaultfunction ~Object
cpp
~Object() =defaultfunction impl
cpp
virtual ObjectImpl * impl() =0Access the internal implementation.
Friends
friend ConnectionImpl
cpp
friend class ConnectionImpl(
ConnectionImpl
);