class ara::tsync::SynchronizedTimeBaseProvider

The move-only class ara::tsync::SynchronizedTimeBaseProvider serves time provider applications for injecting, rate correcting, and validating a synchronized time base [SWS_TS_01101] [SWS_TS_01110]. Updates can either trigger immediate bus transmissions or be scheduled as a local update for the next transmission cycle [SWS_TS_01107] [SWS_TS_01108]. While read accesses are thread-safe, all modifying methods as well as notifier registration require a thread-local or synchronized call [SWS_TS_01109] [SWS_TS_01114].

more ›

Context

The class ara::tsync::SynchronizedTimeBaseProvider provides time provider applications with active control access to a synchronized time base modeled via a ara::core::InstanceSpecifier [SWS_TS_01101]. In AUTOSAR Adaptive, the instance functions as an interface between the providing application logic, the local time-sync daemon, and the connected communication buses. Via this component, the application injects new time values and user-specific payload data into the system, compensates for drift via rate corrections, and acquires validation parameters [SWS_TS_01107] [SWS_TS_01110] [SWS_TS_01114].

Context diagram: Integration of SynchronizedTimeBaseProvider between provider application, validation, and bus transmission. Sources: [SWS_TS_01101], [SWS_TS_01107], [SWS_TS_01114]

Lifecycle

Instantiation takes place explicitly via a ara::core::InstanceSpecifier that must reference a PortPrototype that is typed by a SynchronizedTimeBaseProviderInterface [SWS_TS_01101]. The constructor is declared exception-safe and thread-safe [SWS_TS_01101]. An object of the class is an exclusive move-only object: copy constructor and copy assignment operator are explicitly deleted [SWS_TS_01104] [SWS_TS_01105], while move construction and move assignment are supported [SWS_TS_01102] [SWS_TS_01103].

With respect to concurrency, a strict separation applies: Pure read operations on the status such as GetCurrentTime(), GetRateDeviation(), and GetUserData() are thread-safe and can be executed concurrently [SWS_TS_01109] [SWS_TS_01111] [SWS_TS_01113]. In contrast, all modifying operations, the registration of notifications, and the destruction of the object via the destructor are not thread-safe and require application-side synchronization [SWS_TS_01106] [SWS_TS_01107] [SWS_TS_01114].

Usage Path

Typical usage is divided into registration for validation feedback and cyclic or event-driven time transmission:

• Register validation: If required, the provider application registers a notification object via RegisterTimeValidationNotification() to receive newly recorded time-synchronization data blocks [SWS_TS_01114]. At most one notification receiver can be active; a new registration overwrites an existing one [SWS_TS_01114], whereas UnregisterTimeValidationNotification() detaches the binding [SWS_TS_01115].
• Set time value: In the event of an immediately required distribution, the application calls SetTime(). This sets the local time value and directly initiates transmission on the bus [SWS_TS_01107]. If bus transmission is instead to take place only in the next regular cycle, UpdateTime() is used, whereby the clock is initially updated only locally [SWS_TS_01108].
• Correction and payload data: Via SetRateCorrection(), the drift of the local clock can be adjusted by a correction factor (values less than 1.0 slow down the clock, values greater than 1.0 speed it up) [SWS_TS_01110]. Additional user-specific time base data can be updated via SetUserData() [SWS_TS_01112].

Sequence diagram: Sequence of notifier registration and time update with alternative bus transmission paths. Sources: [SWS_TS_01107], [SWS_TS_01108], [SWS_TS_01114]

Error Scenarios

Methods with return value ara::core::Result<void> signal failures via error codes of type TsyncErrc without rollback semantics:

• TsyncErrc::kInvalidUserDataSize: Occurs for SetTime(), UpdateTime(), and SetUserData() if the passed UserData exceed the maximum length of UserData::kMaxUserDataSize (currently 3 bytes) [SWS_TS_01107] [SWS_TS_01108] [SWS_TS_01112].
• TsyncErrc::kDaemonConnectionLost: Occurs for SetTime() if the IPC connection to the time-sync daemon is interrupted at the time of invocation [SWS_TS_01107].
• TsyncErrc::kLimitsExceeded: Is returned by SetRateCorrection() if the requested rate correction factor is outside the permissible value range [SWS_TS_01110].
• TsyncErrc::kFunctionNotSupported: Is reported by SetRateCorrection() if the underlying platform or time base does not support rate correction [SWS_TS_01110].