Skip to content

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 intregistered() =0
Check whether the object is registered with the router.
virtual intinvoke(const char * command, PropArray & params, bool blocking, PropArray & reply) =0
Invoke a named custom function on the object.
virtual intbroadcast(const char * command, PropArray & params) =0
Broadcast a named custom message to all subscribers.
virtual intgetProperties(PropArray & properties) =0
Retrieve all properties of the object.
virtual intsetProperties(PropArray & properties) =0
Set multiple properties on the object in one call.
virtual intsetProperty(const Property & property) =0
Set a single property on the object.
virtual voidgetProperty(Property & property) =0
Read a single property from the local cache.
virtual intopenProperty(const uint32_t propTag, Stream ** stream) =0
Open a stream associated with a stream-typed property.
virtual intsubscribe(std::function< void(const Indication &)> f) =0
Subscribe to property-change notifications.
virtual voidunsubscribe() =0
Remove all subscriptions from this object.
virtual intsync(unsigned timeout_ms, bool block) =0
Flush pending local property changes to the router.
virtual voiddefer() =0
Move all pending local property changes into a deferred buffer instead of syncing immediately.
virtual intsyncDeferred(unsigned timeout_ms, bool block) =0
Flush all deferred property changes to the router.
virtual boolhasDeferred() =0
Check whether there are deferred property changes waiting.
virtual voidclear() =0
Discard all pending and deferred local property changes.
intsetPriority(uint16_t idFirst, uint16_t idLast, uint8_t prio)
Assign a priority to the tag IDs idFirst..idLast.
uint8_tpriority(uint32_t tag)
Priority of tag; FLAKE_PRIO_NORMAL unless a range of setPriority() covers it.
boolhasUrgentPending()
True while a value of priority FLAKE_PRIO_IMMEDIATE is set but not yet confirmed by the router.
intsetHistoryClass(uint16_t idFirst, uint16_t idLast, uint8_t cls)
Assign a history class to the tag IDs idFirst..idLast.
voidsetHistoryStage(uint8_t stage)
Budget stage the integration has reached (FLAKE_HISTORY_STAGE_NORMAL … FLAKE_HISTORY_STAGE_HOLD). Applies to samples recorded from now on.
voidsetRecordSamples(bool on)
Record every change with its own time.
intflushReport(unsigned timeout_ms)
Send everything pending as one report.
intreportFill(ReportFill * out)
Report the fill level and loss counters of the pending report.
virtual voidref() =0
Increment the reference count.
virtual voidunref() =0
Decrement the reference count.

Protected Functions ​

Name
Object() =default
~Object() =default
virtual ObjectImpl *impl() =0
Access the internal implementation.

Friends ​

Name
classConnectionImpl

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 & 
) =deleted

function operator= ​

cpp
Object & operator=(
    const Object & 
) =deleted

function Object ​

cpp
Object(
    Object && 
) =deleted

function operator= ​

cpp
Object & operator=(
    Object && 
) =deleted

function registered ​

cpp
virtual int registered() =0

Check 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
) =0

Invoke 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 to false for fire-and-forget ("void") calls.
  • reply Output parameters populated by the callee (only meaningful when blocking is true).

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
) =0

Broadcast 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
) =0

Retrieve 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
) =0

Set 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
) =0

Set 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
) =0

Read 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
) =0

Open a stream associated with a stream-typed property.

Parameters:

  • propTag Tag of a TT_STRING_STREAM or TT_BIN_STREAM property.
  • 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
) =0

Subscribe 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() =0

Remove all subscriptions from this object.

function sync ​

cpp
virtual int sync(
    unsigned timeout_ms,
    bool block
) =0

Flush 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() =0

Move 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
) =0

Flush 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) bytes

where 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() =0

Check whether there are deferred property changes waiting.

Return: true if deferred data exists, false otherwise.

function clear ​

cpp
virtual void clear() =0

Discard 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() =0

Increment 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() =0

Decrement 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() =default

function ~Object ​

cpp
~Object() =default

function impl ​

cpp
virtual ObjectImpl * impl() =0

Access the internal implementation.

Friends ​

friend ConnectionImpl ​

cpp
friend class ConnectionImpl(
    ConnectionImpl 
);