class ara::diag::ReleaseHandler

The class ara::diag::ReleaseHandler manages a shared state to determine whether an ongoing diagnostic processing can be cancelled and a shared resource can be released [SWS_DM_01340]. Applications can register a notification function via SetNotifier and query synchronously via MayRelease whether the resource is no longer being used [SWS_DM_01536]. Because default construction and copy operations are prohibited, the instance is transferred via move semantics, with modifications and destruction not being thread-safe.

more ›

Context

In the AUTOSAR Adaptive diagnostic module, the class ara::diag::ReleaseHandler encapsulates a shared state indicating whether an ongoing processing should be cancelled or a shared resource should be released [SWS_DM_01340], AUTOSAR_AP_SWS_Diagnostics §8.23 “Header: ara/diag/release_handler.h”. In the diagnostic architecture, it serves as a synchronization and notification interface between the AUTOSAR diagnostic runtime environment and the application-specific diagnostic handlers. This applies in particular to longer-running or resource-intensive processings, such as those occurring in the context of file and data transfer sessions AUTOSAR_AP_SWS_Diagnostics §7.x “DataTransfer”.

Via the ReleaseHandler, the application is given the possibility to be informed about the termination or cancellation of processing cycles without having to resort to blocking mechanisms. The class thus assumes the role of a decoupler between the internal flow of the diagnostic server and the underlying processing routines of the application.

Lifecycle

The lifecycle of an instance of ReleaseHandler is subject to strict semantic specifications. The class explicitly prohibits parameterless instantiation via the default constructor [SWS_DM_01530], AUTOSAR_AP_SWS_Diagnostics §8.23.1.2.1.1 “Default Constructor”. Since no further public constructor is specified, the actual creation of the object is likely performed internally by the diagnostic server before the instance is passed to the respective service handler. Question Q-05a2e8b6b7deca40 (open) Furthermore, ReleaseHandler is designed as a pure move-only class: both the copy constructor [SWS_DM_01534] and the assignment operator for copies [SWS_DM_01535] are deleted.

Ownership of the instance can be transferred exclusively via move operations. The move constructor is defined as exception-safe (noexcept) and explicitly as thread-safe [SWS_DM_01532], AUTOSAR_AP_SWS_Diagnostics §8.23.1.2.1.2 “Move Constructor”. In contrast, the move assignment operator operator= is likewise exception-safe, but not thread-safe [SWS_DM_01533]. Destruction takes place via the destructor ~ReleaseHandler() [SWS_DM_01531], AUTOSAR_AP_SWS_Diagnostics §8.23.1.2.1.4 “Destructor”, which is exception-safe (noexcept), but must not be called in a thread-safe manner.

Usage Path

The typical usage path comprises registering a notification function as well as synchronously or asynchronously checking the release status. An application registers a callback via the method SetNotifier [SWS_DM_01537]. A callable of type ReleaseHandlerSetNotifier, which is specified as a type alias for std::function<void(void)>, is passed as a parameter [SWS_DM_02079], AUTOSAR_AP_SWS_Diagnostics §8.23.1.1.1 “Type Alias: ReleaseHandlerSetNotifier”. A repeated call to SetNotifier completely overwrites a previously registered function [SWS_DM_01537].

As soon as the shared resource can be released or a cancellation is present, the registered notifier is triggered. Presumably, this call occurs asynchronously in the thread context of the diagnostic server. Question Q-d948326514d200a1 (open) In parallel or within the regular control loop, the application can check via MayRelease() whether the shared resource is no longer in use [SWS_DM_01536]. The method returns true if the resource may be released, and otherwise false [SWS_DM_01536].

Sequence diagram: Flow for notification registration and release of shared resources. Sources: [SWS_DM_01536], [SWS_DM_01537], [SWS_DM_02079].

Error Scenarios

All methods of ReleaseHandler are annotated with noexcept and specified as exception-safe; consequently, no exceptions are thrown and no error codes are returned ([SWS_DM_01531], [SWS_DM_01532], [SWS_DM_01533], [SWS_DM_01536], [SWS_DM_01537]). Error scenarios therefore primarily result from violations of preconditions or insufficient synchronization.

A central precondition when calling SetNotifier is that the passed object must contain a callable target and its execution must not throw any exceptions [SWS_DM_01537]. An empty or invalid function object represents a precondition violation. With regard to concurrency, it must be noted that SetNotifier, the move assignment operator, and the destructor are documented as not thread-safe ([SWS_DM_01531], [SWS_DM_01533], [SWS_DM_01537]). Only MayRelease() and the move constructor are explicitly thread-safe ([SWS_DM_01532], [SWS_DM_01536]). If notifier registrations or assignments are executed concurrently without external synchronization, this leads to undefined behavior.