class ara::tsync::SynchronizedTimeBaseStatus

Class ara::tsync::SynchronizedTimeBaseStatus encapsulates an immutable snapshot of a synchronized time base at the time of creation. It provides methods to read local and synchronized creation timestamps, the synchronization state, status flags for rate correction, and user-specific payload data in a thread-safe manner [SWS_TS_01053]. If the time base has not yet been synchronized since system startup, querying the synchronized time returns an empty optional [SWS_TS_01055]. Because the default constructor is deleted, the object is typically created by the time base and passed to the application by value semantics.

more ›

Context

Class ara::tsync::SynchronizedTimeBaseStatus represents an immutable snapshot of a point in time including all associated states of a synchronized time base. In distributed automotive systems, it serves for temporal decoupling between the dynamically progressing time base and the evaluating application: Instead of querying volatile states directly on the running time base, the application receives a self-consistent image of the time and status information at the time of the object's creation. The class combines time values of the local monotonic clock and the synchronized time and links these with the synchronization state [SWS_TS_01053], status flags for rate correction, and application-specific payload data received from the time base's Time Master [SWS_TS_01056]. Essential interaction partners are thus the providing time base of module tsync and the consuming application.

Lifecycle

The lifecycle of an instance of SynchronizedTimeBaseStatus is designed to preserve snapshot consistency:

• Creation: The default constructor is deleted ([SWS_TS_01061]). Applications therefore cannot instantiate status objects; creation is likely to occur exclusively internally through the respective platform time base. Question Q-ed50a9c63b8e2481 (open)
• Ownership and passing: To return the snapshot to applications by value semantics, the class provides a noexcept copy constructor ([SWS_TS_01058]). For resource-efficient ownership transfers, a move constructor ([SWS_TS_01057]) as well as corresponding copy and move assignment operators ([SWS_TS_01060], [SWS_TS_01059]) also exist. The receiving application assumes full ownership of the object.
• Destruction: The destructor is specified as a default destructor with noexcept ([SWS_TS_01062]) and releases resources deterministically.
• Concurrency: All read methods for status querying are defined as thread-safe and exception safe ([SWS_TS_14176], [SWS_TS_01055]). Multiple threads can thus evaluate the same snapshot concurrently and without additional synchronization. Only the assignment and construction operations are non_threadsafe ([SWS_TS_01057], [SWS_TS_01058]).

Usage Path

Once an application has received an instance of SynchronizedTimeBaseStatus from the time base ([SWS_TS_01058]), evaluation typically follows a defined sequence:

First, the application checks the synchronized creation time using GetCreationTime() ([SWS_TS_01055]). If the time base has never been synchronized since system startup, the call returns an empty ara::core::Optional. In this case, the application can fall back to the creation timestamp relative to the local monotonic clock (ara::core::SteadyClock) via GetCreationLocalTime() ([SWS_TS_14176]).

In the synchronized state, the application determines the exact synchronization phase via GetSynchronizationStatus() ([SWS_TS_01053]) and checks with GetLeapJump() ([SWS_TS_01054]) whether and in which direction a time jump has occurred since the previous snapshot creation. Subsequently, it is checked whether a rate correction is being calculated (GetRateCorrected(), [SWS_TS_14226]) and whether the calculated rate deviation exceeds the threshold rateCorrectionThreshold (GetRateExceeded(), [SWS_TS_14229]). Finally, payload data transmitted by the Time Master can be queried via GetUserData() ([SWS_TS_01056]).

Sequence diagram: Typical query and evaluation of a status snapshot by an application. Sources: [SWS_TS_01058], [SWS_TS_01055], [SWS_TS_14176], [SWS_TS_01053], [SWS_TS_14229], [SWS_TS_01056].

Error Scenarios

The interface of SynchronizedTimeBaseStatus is declared entirely as noexcept and does not throw any C++ exceptions. Invalid states or errors are signaled via semantic return types:

A missing synchronization reference is represented by an empty ara::core::Optional for GetCreationTime() if the time base has exhibited the status kNotSynchronizedUntilStartup since system startup ([SWS_TS_01055]). Threshold violations during frequency tracking are reported by GetRateExceeded() via the boolean value in ara::core::Result<bool> ([SWS_TS_14229]). Standardized error codes are not specified for GetRateCorrected() ([SWS_TS_14226]) and GetRateExceeded() ([SWS_TS_14229]); interpretation: An error state conveyed in the Result is likely to indicate internal platform or driver issues. Question (open)