class ara::diag::CancellationHandler

The class ara::diag::CancellationHandler informs diagnostic applications about the premature cancellation of an ongoing processing in Diagnostic Management [SWS_DM_00608]. The object created by the DM core allows the service processor to query the cancellation status via IsCanceled() or to be notified via callback using SetNotifier() in order to immediately cease service processing [SWS_DM_00615]. Once set, a cancellation status is irrevocable, and accesses to the instance must be secured on the application side because the interface is not thread-safe.

more ›

Context

Within module diag, the class ara::diag::CancellationHandler acts as a shared state indicator that indicates whether ongoing diagnostic processing is to be canceled prematurely [SWS_DM_00608]. In the AUTOSAR Adaptive Platform, the class mediates between the server instance of Diagnostic Management (DM) and the executing application logic, such as during the processing of manufacturer-specific UDS services (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.24 “Custom Diagnostic Services”, [SWS_DM_00502]).

If an active diagnostic conversation is canceled by external events or protocol requirements, the diagnostic server instance is obligated to cease the started activity as quickly as possible [SWS_DM_00278]. This cancellation is signaled to the service processor via the CancellationHandler, so that resource-intensive computations are aborted and the inadmissible sending of diagnostic responses prior to the start of their transmission is prevented [SWS_DM_00279].

Lifecycle

Instantiation of ara::diag::CancellationHandler is subject to the exclusive control of the diagnostic framework: The default constructor is explicitly deleted for applications (delete), so instances can be created exclusively by the DM core [SWS_DM_00609]. To ensure unique state assignment, the class is specified as a non-copyable single instance; copy constructor [SWS_DM_00611] and copy assignment operator [SWS_DM_00613] are deleted.

In contrast, the class supports move semantics: The move constructor [SWS_DM_00610] and the move assignment operator [SWS_DM_00612] are declared as default implementations as noexcept. This presumably allows the framework to efficiently transfer ownership of the instance into downstream execution contexts. Question (open)

In terms of state, the instance exhibits monotonic behavior. Immediately after initialization, IsCanceled() signals the value false [SWS_DM_00984]. As soon as the associated diagnostic conversation is canceled, the state changes to true. This cancellation status persists irreversibly until the destruction of the instance [SWS_DM_00984].

State diagram: Lifecycle and status transitions of the CancellationHandler. Sources: [SWS_DM_00609], [SWS_DM_00984], AUTOSAR_AP_SWS_Diagnostics §7.3.2 “Return of cancellation status”

Usage Path

Typical usage of the handler is divided into the following coordinated steps:

1. Provisioning: Upon arrival of a diagnostic request, the DM core creates the CancellationHandler object and forwards it to the processing routine of the diagnostic application (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.24 “Custom Diagnostic Services”, [SWS_DM_00609]).
2. Registration or polling: By means of SetNotifier(), the application registers a notification function of type ara::diag::CancellationHandler::CancellationHandlerSetNotifier ([SWS_DM_02075]), which is called when a cancellation occurs [SWS_DM_00615]. Alternatively or concurrently, it queries IsCanceled() cyclically [SWS_DM_00614].
3. Signaling: If the DM cancels the conversation, the status in the handler changes to true [SWS_DM_00984] and the registered notifier is triggered [SWS_DM_00615].
4. Cancellation: The application immediately ceases the started work [SWS_DM_00278]. If the response has not yet been transmitted, the DM suppresses transmission [SWS_DM_00279].
5. Completion: After completion of processing, the handler object is destroyed together with the service context.

Sequence diagram: Interaction patterns between DM core, CancellationHandler, and diagnostic application. Sources: [SWS_DM_00278], [SWS_DM_00614], [SWS_DM_00615], [SWS_DM_00984], [SWS_DM_00609], [SWS_DM_00279]

Error Scenarios

The interface of ara::diag::CancellationHandler features an error-free design. All methods such as IsCanceled() [SWS_DM_00614], SetNotifier() [SWS_DM_00615], as well as the move operations [SWS_DM_00610] [SWS_DM_00612] are exception-safe (noexcept) and return no error codes.

Calling SetNotifier() multiple times does not lead to an error: Subsequent registrations completely overwrite the previously set callback [SWS_DM_00615], [SWS_DM_01348].

Thread safety requires special attention: All member functions (IsCanceled, SetNotifier) and the callback type are explicitly declared as not thread-safe [SWS_DM_00614], [SWS_DM_00615], [SWS_DM_02075]. If status queries or notifier registrations are performed across thread boundaries, the application must deploy external protection mechanisms. Furthermore, the callback is likely to be called synchronously in the triggering thread of the DM, which is why application-side notifier functions should remain non-blocking. Question Q-26c43c035d4f18a3 (open)