class ara::phm::SupervisedEntity

Template class ara::phm::SupervisedEntity serves for functional monitoring in Platform Health Management and enables applications to report defined checkpoints [SWS_PHM_01127]. The instance is bound to an InstanceSpecifier, movable, but not copyable [SWS_PHM_01123], [SWS_PHM_01212]. While ReportCheckpoint() is thread-safe, asynchronous activation via Enable(), deactivation via Disable(), and the destructor are not thread-safe [SWS_PHM_01130], [SWS_PHM_01211].

more ›

Context

Template class ara::phm::SupervisedEntity represents a functional unit to be supervised in the Platform Health Management (PHM) of AUTOSAR Adaptive [SWS_PHM_01123]. It serves an application as an interface to report reaching defined control points (checkpoints) to PHM [SWS_PHM_01127]. Based on the reported checkpoints, the PHM subsystem monitors the temporal and logical behavior of the entity. Assignment to the architecture and associated modeling elements is performed via an ara::core::InstanceSpecifier referencing a corresponding port [SWS_PHM_01123]. Furthermore, the class allows the application to selectively activate or deactivate monitoring as needed [SWS_PHM_01130], [SWS_PHM_01380].

Lifecycle

An object of type ara::phm::SupervisedEntity is instantiated explicitly by specifying an ara::core::InstanceSpecifier [SWS_PHM_01123]. The class implements move semantics: Move constructor [SWS_PHM_01214] and move assignment operator [SWS_PHM_01215] transfer the resource and are specified as thread-safe and exception-safe. Copy constructor [SWS_PHM_01212] and copy assignment operator [SWS_PHM_01213] are deleted (delete), so that instances remain bound to their owner. Destructor ~SupervisedEntity() releases the entity and is declared as not thread-safe [SWS_PHM_01211]; destruction must therefore be performed in a synchronized manner if multiple threads are involved.

After creation, supervision can be activated via Enable() [SWS_PHM_01130] or suspended via Disable() [SWS_PHM_01380]. Both control functions return a ara::core::Future<void> and are not thread-safe, whereas the regular reporting of checkpoints via ReportCheckpoint() can be performed in a thread-safe manner [SWS_PHM_01127].

Usage Path

The typical interaction is divided into initialization, optional activation of supervision, cyclic or event-based reporting of checkpoints, and releasing the instance. The following sequence diagram illustrates this sequence:

Sequence diagram: Typical sequence of instantiation, activation, checkpoint reporting, and deactivation of a SupervisedEntity. Sources: [SWS_PHM_01123], [SWS_PHM_01130], [SWS_PHM_01127], [SWS_PHM_01380], [SWS_PHM_01211]

First, the application instantiates the object with the configured InstanceSpecifier [SWS_PHM_01123]. If supervision is to be activated (depending on the state of the function group), the application invokes Enable() and, if necessary, synchronizes via the returned ara::core::Future<void> [SWS_PHM_01130]. During execution, the application reports reached checkpoints via ReportCheckpoint(checkpointId) [SWS_PHM_01127]. Prior to termination or upon function state transitions, supervision can be suspended via Disable() [SWS_PHM_01380] before the instance is finally destroyed [SWS_PHM_01211].

Error Scenarios

Error conditions are signaled in ara::phm::SupervisedEntity primarily via asynchronous error codes in return values as well as via reported system violations:

• Runtime error during state control: If a caller attempts to invoke Enable() [SWS_PHM_01130] or Disable() [SWS_PHM_01380] while an activation or deactivation request is already in progress, the call fails. In this case, the resulting ara::core::Future reports the error code PhmErrc::kServiceNotReady (rollback semantics).
• Construction violations: When calling the constructor [SWS_PHM_01123], strict preconditions are checked:
  • AraNotInitializedViolation: The ARA runtime environment is not yet initialized.
  • InstanceSpecifierMappingIntegrityViolation: The identifier cannot be resolved in the context of the executable or does not refer to a PortPrototype.
  • PortInterfaceMappingViolation: The PortPrototype typed with PhmSupervisedEntityInterface is not referenced by any SupervisionCheckpoint.
  • ProcessMappingViolation: The calling process is not authorized for the corresponding checkpoints in the model.
  • InstanceSpecifierAlreadyInUseViolation: The identifier is already used by another instance in the same process.
• Violation during checkpoint reporting: If ReportCheckpoint() is invoked by a process that is not mapped via SupervisionCheckpoint.process in the model, this results in a InsufficientPermissionsViolation [SWS_PHM_01127].