class ara::phm::RecoveryAction

Abstract class ara::phm::RecoveryAction enables applications to provide application-specific recovery actions for Platform Health Management [SWS_PHM_01141]. After instantiation, calling Offer() enables readiness to receive from the Phm daemon, so that overridden method RecoveryHandler is called when monitoring errors are detected [SWS_PHM_01143]. If the error cannot be resolved on the application side, the system escalates by triggering the watchdog. Copy and move operations are completely disallowed for safety reasons, and management calls such as Offer() are not thread-safe.

more ›

Context

Class ara::phm::RecoveryAction is an abstract base class in the Platform Health Management (PHM) module of the AUTOSAR Adaptive Platform. It serves as a standardized interface for functional applications to provide specific recovery and error-handling actions initiated by PHM when monitoring errors are detected.

The essential interaction partners include:

• The deriving application component: Interpretation: This is presumably typically located in State Management, as the latter is responsible for coordinated system reactions and is directly named in the error context. Question Q-714ff81a33aa3e92 (open) The application implements application-specific error recovery by overriding method RecoveryHandler [SWS_PHM_01142].
• The Phm daemon: Manages the registration of recovery actions via Offer [SWS_PHM_01143] and controls the invocation of the registered handler [SWS_PHM_01142] when errors are identified.
• The watchdog: If application-side recovery cannot be carried out successfully, PHM takes over further error handling and triggers the watchdog for safeguarding [SWS_PHM_01142].

The logical link to the AUTOSAR model is established during instantiation via an ara::core::InstanceSpecifier, which must reference a PPortPrototype of a PhmRecoveryAction interface [SWS_PHM_01141].

Lifecycle

An instance is created via the explicit constructor by passing the matching instance specifier [SWS_PHM_01141]. This constructor is thread-safe (thread-safe) and exception-safe (noexcept).

Because a RecoveryAction is permanently bound to a specific port, copy and move operations are completely disallowed: Both copy constructor [SWS_PHM_01150] and copy assignment operator [SWS_PHM_01152] are deleted (= delete). Move constructor [SWS_PHM_01149] and move assignment operator [SWS_PHM_01151] are likewise deleted. The specification justifies this on the grounds that moving after offering the instance could result in RecoveryHandler being called prior to the complete construction of the derived class, which would cause undefined behavior or unhandled exceptions and jeopardize system safety [SWS_PHM_01149], [SWS_PHM_01151].

The lifecycle comprises two distinct states:

• Not offered: Immediately after construction and after calling StopOffer [SWS_PHM_01144], the instance is inactive. Calls to RecoveryHandler are prevented.
• Offered: By calling Offer() [SWS_PHM_01143], the action is activated with the Phm daemon and released for handler calls.

The object is released via the virtual destructor [SWS_PHM_01145]. Regarding concurrency, the constructor and RecoveryHandler are specified as thread-safe, whereas Offer(), StopOffer(), and the destructor are not thread-safe (not thread-safe) [SWS_PHM_01141], [SWS_PHM_01142], [SWS_PHM_01143], [SWS_PHM_01144], [SWS_PHM_01145]. Interpretation: In practice, calling StopOffer() presumably always must occur prior to destroying an instance in order to reliably rule out asynchronous handler calls during object teardown. Question Q-a1f47898bed925fd (open)

State diagram: Lifecycle states of RecoveryAction with activation by Offer and deactivation by StopOffer. Sources: [SWS_PHM_01141], [SWS_PHM_01143], [SWS_PHM_01144], [SWS_PHM_01145]

Usage Path

Typical usage is structured into a fixed call sequence:

1. Definition of a derived class implementing pure virtual member function RecoveryHandler [SWS_PHM_01142].
2. Instantiation of the derived object by specifying instance specifier [SWS_PHM_01141].
3. Call of Offer() to provide the recovery action to the Phm daemon [SWS_PHM_01143].
4. Reaction to errors: If PHM detects an error, it calls RecoveryHandler(executionError, supervision) [SWS_PHM_01142]. The method returns a ara::core::Future<void> via which the result of the error handling is reported.
5. Call of StopOffer() as soon as the instance is no longer intended to service recovery actions [SWS_PHM_01144].
6. Destruction of the object via destructor [SWS_PHM_01145].

Sequence diagram: Typical call sequence during registration, error notification, and deregistration of a recovery action. Sources: [SWS_PHM_01141], [SWS_PHM_01142], [SWS_PHM_01143], [SWS_PHM_01144], [SWS_PHM_01145]

Error Scenarios

Specific error conditions must be considered in the context of model configuration and operation:

• Model and validation violations during construction [SWS_PHM_01141]:
  • AraNotInitializedViolation: The ARA runtime environment was not initialized prior to instantiation.
  • InstanceSpecifierMappingIntegrityViolation: The instance specifier cannot be resolved in the model or does not reference a PortPrototype.
  • PortInterfaceMappingViolation: The port prototype referenced via RecoveryNotificationToPPortPrototypeMapping is not typed by a PhmSupervisionRecoveryNotificationInterface.
  • ProcessMappingViolation: At runtime, no suitably modeled process exists for the instance ref.
  • InstanceSpecifierAlreadyInUseViolation: The instance specifier is already in use within the current process.
• Communication error during offering [SWS_PHM_01143]: If communication with the Phm daemon fails, Offer() returns a result with error code PhmErrc::kOfferFailed.
• Unrecoverable errors in recovery [SWS_PHM_01142]: If State Management cannot resolve the reported error, the Future returned by RecoveryHandler returns error PhmErrc::kSMCanNotHandleRecovery. Thereupon, Platform Health Management intervenes and triggers the watchdog.