struct ara::tsync::UserData

The structure ara::tsync::UserData serves to transmit compact application-specific user data within synchronized time bases. It manages a static buffer with an immutable upper limit of three bytes defined via kMaxUserDataSize [SWS_TS_14231]. Applications write user data into the array and indicate the number of actually valid bytes via the field size [SWS_TS_14232]. As a central boundary condition, the applying program logic must ensure that size never exceeds the defined maximum capacity and that accesses to uninitialized buffer areas are avoided.

more ›

Context

The data structure ara::tsync::UserData serves within the functional cluster for time synchronization (tsync) of the AUTOSAR Adaptive Platform to encapsulate application-specific user data within synchronized time bases. The structure is declared in header file ara/tsync/synchronized_time_base_status.h. Its primary responsibility is to provide a compact, statically sized memory area for supplementary application data transmitted or evaluated together with time information. The maximum size of this user data is set to exactly three bytes by the static constant kMaxUserDataSize [SWS_TS_14231]. Array data of type ara::core::Array<ara::core::Byte, kMaxUserDataSize> is used for buffering the actual user data bytes [SWS_TS_14233]. This buffer is supplemented by field size, which indicates the number of actually valid user data bytes in the buffer [SWS_TS_14232]. Interpretation: Due to its definition location in header ara/tsync/synchronized_time_base_status.h, UserData is likely to serve primarily as a status field for transmitting small supplementary application-related information such as control flags or counters. Question Q-a0fb20686141f042 (open) Time-providing services and receiving applications that query or forward the status of a synchronized time base typically act as interaction partners.

Lifecycle

As an ordinary C++ structure (value object), UserData has no complex internal lifecycle and completely avoids dynamic memory allocations. Instances typically originate on the stack or as an embedded data member of higher-level status structures. Initialization takes place directly via member initialization or standard C++ assignment. Regarding ownership, the structure is subject to value semantics: creating components fully own their local instance and pass it by copy or reference to interfaces. Since UserData implements no internal synchronization mechanisms or mutex locks, concurrent read and write access from multiple threads to the same instance is not thread-safe. Applications must protect concurrent accesses through external synchronization measures, whereas independent instances can be used safely in concurrent contexts. Destruction requires no explicit cleanup of resources because the contained data member data [SWS_TS_14233] is statically allocated.

Usage Path

A typical usage path comprises populating, forwarding, and evaluating the data buffer. First, a transmitting or status-providing component creates an instance of UserData. The user data is then copied into the array data, whereby a maximum of kMaxUserDataSize bytes may be occupied [SWS_TS_14231], [SWS_TS_14233]. Immediately thereafter, the component sets the field size to the actual number of bytes written [SWS_TS_14232]. On the receiver side, the processing application first checks the value of size [SWS_TS_14232]. If size is greater than zero, the application reads exactly this valid prefix from buffer data [SWS_TS_14233]. Values outside this range, i.e., from index size to kMaxUserDataSize - 1, are ignored because they may contain undefined or outdated residual data.

Error Scenarios

Error situations in UserData result primarily from inconsistencies between the size specification and the buffer capacity. If the field size assumes a value that exceeds the defined maximum size kMaxUserDataSize of three bytes [SWS_TS_14231], this represents a violation of specification limits. In such a case, iterative reading of data [SWS_TS_14233] risks buffer overflows or out-of-bounds accesses to the array. Another risk consists of reading data erroneously when size is equal to zero [SWS_TS_14232], as no valid user data is present in this state. Error codes or exceptions are not generated by the structure itself; validating preconditions – especially size <= kMaxUserDataSize – is therefore entirely the responsibility of the applying program logic.