class ara::diag::OperationCycle

The ara::diag::OperationCycle class provides the application with functions for controlling and monitoring diagnostic operation cycles [SWS_DM_00752]. Instances are bound to a modeled port via an ara::core::InstanceSpecifier, are neither copyable nor movable, and may only exist once per identifier in the process. Via SetNotifier, a notification for cycle changes can be configured, and a restart of the operation cycle can be triggered by means of RestartOperationCycle [SWS_DM_01102]. With the exception of the thread-safe constructor, all methods as well as the destructor are not thread-safe and require application-side synchronization in case of parallel access.

more ›

Context

The ara::diag::OperationCycle class implements the DiagnosticOperationCycleInterface within AUTOSAR Adaptive Diagnostics and provides functions for handling and controlling operation cycles. It serves as an interface between the adaptive application and Diagnostic Management to monitor or specifically reset states of operation cycles.

The connection to the overall system takes place via an ara::core::InstanceSpecifier, which is passed during the constructor call [SWS_DM_00752]. This identifier references an PortPrototype defined in the model. In this context, the model prescribes a unique mapping: an PortPrototype referenced by an DiagnosticOperationCyclePortMapping must be typed by the DiagnosticOperationCycleInterface [SWS_DM_00752]. In addition to control, the class interacts via a callback interface of type ara::diag::OperationCycle::OperationCycleSetNotifier (defined as std::function<void(void)>), through which notifications upon a change of the operation cycle are transmitted to the application [SWS_DM_02078], [SWS_DM_00755].

Lifecycle

Creation of ara::diag::OperationCycle takes place explicitly by specifying the port instance specification via the constructor OperationCycle(const ara::core::InstanceSpecifier &specifier) [SWS_DM_00752]. The constructor is specified as exception-safe (exception safe) and thread-safe (thread-safe) [SWS_DM_00752].

With regard to ownership and copy semantics, the class is modeled as a strict single object representing a fixed 1:1 binding to the modeled port. Copying and moving are completely prevented:

• The copy constructor is deleted (delete) to rule out duplications [SWS_DM_01598].
• The move constructor is deleted (delete) [SWS_DM_01599].
• The copy assignment operator is deleted (delete) [SWS_DM_01596].
• The move assignment operator is deleted (delete) [SWS_DM_01597].

In addition, the framework prohibits multiple assignment: an InstanceSpecifier must not be repeatedly used for instantiation within the same process [SWS_DM_00752]. Release takes place in the destructor ~OperationCycle() [SWS_DM_00753]. In contrast to the constructor, the destructor is not thread-safe (not thread-safe), although it is declared as exception-safe [SWS_DM_00753]. The other methods of the class as well as the callback type are also not thread-safe [SWS_DM_00755], [SWS_DM_01102], [SWS_DM_02078], so parallel accesses to the same instance must be synchronized on the application side.

Usage Path

A typical usage path comprises instantiation, optional registration of a handler for cycle changes, repeatedly triggering the cycle restart, and release:

1. Instantiation: The application creates the object OperationCycle, passing the corresponding InstanceSpecifier [SWS_DM_00752].
2. Register notifier: Via the method SetNotifier, the application registers a callback function of type OperationCycleSetNotifier [SWS_DM_00755], [SWS_DM_02078]. This function is called when the operation cycle changes. A consecutive call of SetNotifier completely overwrites the previously registered notifier [SWS_DM_00755].
3. Restart operation cycle: By means of RestartOperationCycle(), the application triggers the restart of the operation cycle [SWS_DM_01102]. Diagnostic Management updates the cycle and notifies the registered callback upon state changes [SWS_DM_00755]. The notification is likely to occur asynchronously in the context of Diagnostic Management. Question Q-7cd22debf6fa91d7 (open)
4. Destruction: When shutting down the software component, the object is destroyed via the destructor [SWS_DM_00753].

Sequence diagram: Sequence of instantiation, notifier registration, and restart of the operation cycle. Sources: [SWS_DM_00752], [SWS_DM_00755], [SWS_DM_01102], [SWS_DM_02078].

Error Scenarios

Errors during initialization are signaled by the framework as violations, since the constructor is declared as noexcept [SWS_DM_00752]:

• InstanceSpecifierMappingIntegrityViolation: The InstanceSpecifier cannot be resolved in the context of the executable or references an element that is not an PortPrototype [SWS_DM_00752].
• PortInterfaceMappingViolation: The PortPrototype referenced by DiagnosticOperationCyclePortMapping is not typed by an DiagnosticOperationCycleInterface [SWS_DM_00752].
• ProcessMappingViolation: Although a matching instance reference exists, no matching modeled process was found for the runtime process [SWS_DM_00752].
• InstanceSpecifierAlreadyInUseViolation: The constructor was called with an InstanceSpecifier that is already used within the current process [SWS_DM_00752].

In regular operation, the methods SetNotifier and RestartOperationCycle return a ara::core::Result<void> [SWS_DM_00755], [SWS_DM_01102]. For both functions, no specific error codes are defined in the standard (“This function does not specify any standardized errors.”) [SWS_DM_00755], [SWS_DM_01102]. The use of the Result type is likely primarily intended to ensure a uniform interface design and offer room for implementation-specific error states. Question Q-2c59a287c0d5783a (open)