class ara::tsync::ProviderTimeBaseValidationNotification

The abstract class ara::tsync::ProviderTimeBaseValidationNotification serves as a callback interface for providing recorded time base measurement data to a validator application. Implementations receive measurement blocks of the time master via SetMasterTimingData [SWS_TS_00421] and measurement data of the pdelay responder via SetPdelayResponderData [SWS_TS_00423]. The methods are specified as noexcept, but are not thread-safe, which is why concurrent invocations on the same instance must be avoided.

more ›

Context

The class ara::tsync::ProviderTimeBaseValidationNotification acts as an abstract callback interface for validating time bases within the synchronization module. Via this interface, a receiving validator application is notified as soon as new recorded measurement data blocks are available for a monitored time base. The interface defines handover points for specific measurement data of the time master according to [SWS_TS_00421] as well as for measurement data of the pdelay responder mechanism according to [SWS_TS_00423]. The interaction partners here are typically the internal provider mechanism of the time synchronization stack as the data source and an application-side validation instance that evaluates the recorded time data.

Life cycle and concurrency

As an abstract interface, ara::tsync::ProviderTimeBaseValidationNotification is derived and implemented by the concrete validation application. The lifetime of the instantiated implementation is the responsibility of the application. The class has a default virtual destructor declared as exception-safe (noexcept) [SWS_TS_01301]. This ensures that derived class instances can be destroyed polymorphically and safely in terms of resources during destruction. Regarding concurrency, the notification methods are explicitly classified as not thread-safe (non_threadsafe) [SWS_TS_00421], [SWS_TS_00423]. This means that invocations of SetMasterTimingData and SetPdelayResponderData for the same instance must not occur unprotected from competing threads; the invoking time base provider is expected to issue these invocations sequentially, or the application must ensure synchronization. Question Q-8f59bb65825ead66 (open)

Usage Path

The typical sequence begins with the provision of a class derived from ara::tsync::ProviderTimeBaseValidationNotification by the validator application. The instance is likely to be registered with the time base provider to subscribe to corresponding measurement data. Question Q-0ddb9ee8a3e8f381 (open) As soon as the time stack has completed new measurement cycles of the time base, it delivers the recorded blocks via the pure virtual methods of the interface. For analyzing the time master, SetMasterTimingData is invoked with parameter measurementData of type TimeMasterMeasurementType [SWS_TS_00421]. If measurement data for signal propagation delay measurement is available for the time base, the provider transmits it via SetPdelayResponderData with parameter measurementData of type PdelayResponderMeasurementType [SWS_TS_00423]. After monitoring operation has ended, the application destroys the instance orderly via the virtual destructor [SWS_TS_01301].

Sequence diagram: Typical notification of a validator application about new time base measurement data blocks. Sources: [SWS_TS_00421], [SWS_TS_00423], [SWS_TS_01301]

Error Scenarios and Boundary Conditions

Both SetMasterTimingData and SetPdelayResponderData are specified as noexcept and carry the classification exception safe [SWS_TS_00421], [SWS_TS_00423]. Implementations of this interface must therefore not pass exceptions to the invoking synchronization provider. The methods return no value (void); feedback regarding faulty or implausible measurement data is thus not provided directly via the method invocation. Since the interface is declared as non_threadsafe, a concurrent invocation without external synchronization leads to undefined behavior. A precondition for receiving the data is an intact object whose lifetime must be maintained throughout the entire period of callback provision until destruction via the destructor [SWS_TS_01301].