class ara::nm::NetworkHandle

Usage and lifecycle

The class NetworkHandle acts as an access object to a network handle addressed via an ara::core::InstanceSpecifier, and is intended for State Management [SWS_ANM_01000]. Instantiation is performed by passing the InstanceSpecifier of an NetworkManagementPortInterface port prototype [SWS_ANM_01001]. Since the class is declared as final, it cannot be used as a base class for derivation [SWS_ANM_01000].

Move Semantics and Concurrency

Objects of this class have move-only semantics: The copy constructor [SWS_ANM_01005] and the copy assignment operator [SWS_ANM_01006] are deleted (= delete). Instead, instances can be transferred via the move constructor [SWS_ANM_01003] and the move assignment operator [SWS_ANM_01004].

Regarding thread safety, the following requirements apply:

• The constructor with InstanceSpecifier is thread-safe (thread-safe) [SWS_ANM_01001].
• For the move constructor, thread safety is implementation-defined (implementation-defined) [SWS_ANM_01003].
• The destructor [SWS_ANM_01002] and the move assignment [SWS_ANM_01004] are explicitly designated as not thread-safe (not thread-safe). Interpretation: Since thread safety is not guaranteed, the calling context is likely responsible for external synchronization if multiple threads use the same handle. Question Q-7172baaffab79218 (open)

Error handling

All constructors, assignment operators, and the destructor are declared as noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Exceptions or error return values are not provided in this class interface.

The type alias NetworkStateChangeNotifier from the header ara/nm/network_handle.h defines a function wrapper for callback functions upon network state changes [SWS_ANM_01020]. The signature std::function<void(const NetworkStateType&)> accepts the new state as a parameter as a constant reference to NetworkStateType and has no return value [SWS_ANM_01020].

The notifier is used in the monitoring of the network management via two registration points:

• To signal the effective network state, the notifier is registered via RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. Alternatively, a template overload allows passing a user-defined executor in whose context the notifier is executed [SWS_ANM_01015]. At most one notifier can be active per instance [SWS_ANM_01010].
• For notifications about the requested network state, registration takes place via RegisterNetworkRequestedStateChangeNotifier, either directly [SWS_ANM_01012] or with the specification of a target executor [SWS_ANM_01014]. Here, too, at most one handler is permitted [SWS_ANM_01012].

Regarding error handling, all registration functions return a ara::core::Result<void>; if registration fails, the error NmErrc::kInvalidHandler is reported [SWS_ANM_01010], [SWS_ANM_01012]. This is likely to occur in particular if an incompletely initialized or empty function object is passed. Question Q-04452871df619a94 (open)

As a restriction, NetworkStateChangeNotifier is specified as not thread-safe (not thread-safe) [SWS_ANM_01020]. The associated registration functions are also designed to be not thread-safe [SWS_ANM_01010], [SWS_ANM_01012]. Callers must therefore ensure that assignment and registration take place synchronized or sequentially.

The enumeration NetworkStateType represents the state of a network in module anm (Adaptive Network Management) [SWS_ANM_01358]. It distinguishes between the inactive state kNoCom = 0 (if not all assigned networks are in the state FULL_COM) and the active state kFullCom = 1 (when all assigned networks are FULL_COM) [SWS_ANM_01358].

The type is used in various ways in the interfaces of ara/nm/network_handle.h:

• State Query: The method GetNetworkState() returns the current effective network state synchronously and in a thread-safe manner as ara::core::Result<NetworkStateType> [SWS_ANM_01007]. Likewise, GetNetworkRequestedState() reads the currently requested state for a PNC, VLAN, or physical network in a thread-safe manner [SWS_ANM_01008].
• State Request: A state for a PNC, a VLAN, or a physical network is actively requested (kFullCom) or released (kNoCom) via SetNetworkRequestedState(NetworkStateType networkState) [SWS_ANM_01009]. This operation is specified as not thread-safe [SWS_ANM_01009].
• Event Notification: The type is passed as a parameter via the function wrapper NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>) to inform application logic about state changes [SWS_ANM_01020].

Error Handling: When querying or setting NetworkStateType via the mentioned methods, code NmErrc::kServiceNotAvailable can be returned in ara::core::Result in the event of an error [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

use

The function RegisterNetworkRequestedStateChangeNotifier from header ara/nm/network_handle.h registers a callback function for notification of changes to the requested network state [SWS_ANM_01012]. A NetworkStateChangeNotifier is passed to it as a parameter. A maximum of one notifier can be registered for changes to the requested state [SWS_ANM_01012]. The function is declared as noexcept and returns a ara::core::Result<void>.

Error handling

If an error occurs during registration, it is reported via the ara::core::Result with the specific error code NmErrc::kInvalidHandler [SWS_ANM_01012]. Interpretation: This error is likely triggered if the passed notifier is invalid or not callable. Question Q-57a28e90a933e6de (open)

Concurrency and Limitations

The function is specified as not thread-safe (not thread-safe) [SWS_ANM_01012]. Callers must therefore strictly synchronize concurrent accesses and registration attempts from multiple threads externally.

Interaction

As an alternative to direct execution, there is a template overload of the function [SWS_ANM_01014], which additionally accepts a executor parameter. This allows operating the notifier in an explicitly provided execution context; this overload is also not thread-safe and reports NmErrc::kInvalidHandler in the event of an error [SWS_ANM_01014].

The template function RegisterNetworkRequestedStateChangeNotifier declared in header ara/nm/network_handle.h registers a callback of type NetworkStateChangeNotifier to be notified of state changes of the requested network [SWS_ANM_01014]. Via the additional parameter executor of type ExecutorT&&, the desired execution context is defined in which this notifier is to be executed upon state changes. The synchronous call for handler registration is declared as noexcept and returns a ara::core::Result<void> to the caller.

For error handling, the interface signals issues via the return type ara::core::Result. If an invalid handler is passed, the operation fails and the function returns the specific error code NmErrc::kInvalidHandler [SWS_ANM_01014].

Regarding concurrency and call restrictions, the function is explicitly specified as not thread-safe [SWS_ANM_01014]. This means that callers must provide external synchronization for concurrent accesses to the same handle instance in order to avoid data conflicts.

In the system interaction, this function represents an extension of the parameter-poorer variant [SWS_ANM_01012], which registers a maximum of one notifier for changes of the requested state. Interpretation: Since the base specification in [SWS_ANM_01012] allows a maximum of one notifier, this call is also expected to occupy the same notifier slot and overwrite a previously set handler upon re-registration. Question Q-5d8c1832558ac15b (open)

use

The function RegisterNetworkStateChangeNotifier is used to register a notifier for the effective network state [SWS_ANM_01010]. It is declared in header ara/nm/network_handle.h and defined as noexcept [SWS_ANM_01010]. A NetworkStateChangeNotifier notifier is passed as a parameter; the return is synchronous via ara::core::Result<void> [SWS_ANM_01010]. A maximum of one notifier can be registered for the state [SWS_ANM_01010].

Error handling

In the event of an error, the ara::core::Result returns the error code NmErrc::kInvalidHandler [SWS_ANM_01010]. This signals to the caller that the passed handler is invalid [SWS_ANM_01010].

Concurrency and Limitations

The interface is explicitly specified as not thread-safe [SWS_ANM_01010]. Calling components must therefore ensure that calls to RegisterNetworkStateChangeNotifier do not occur concurrently without external synchronization. Since the specification provides for a maximum of one notifier, repeated calls presumably overwrite or reject an existing registration [SWS_ANM_01010]. Question Q-5e3ac4e4d2b33e9f (open)

Interaction

The function is directly related to the template overload [SWS_ANM_01015]. While the base function binds the notifier without an explicit execution context, [SWS_ANM_01015] allows passing an additional parameter ExecutorT&& executor to control the execution of the handler in a specified context [SWS_ANM_01015]. Both variants implement requirements from RS_Nm_00051, are defined in the same header, and share the classification not thread-safe as well as the error NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

The template function RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) from header ara/nm/network_handle.h registers a callback function to monitor changes of the effective network state. Compared to the parameter-poorer variant, this interface accepts not only the notifier of type NetworkStateChangeNotifier, but additionally a user-defined execution context executor (ExecutorT&&), via which notifications are asynchronously scheduled and processed.

Error Handling and Return Values

The function is declared as noexcept and signals the result via a ara::core::Result<void> [SWS_ANM_01015]. If an error occurs during registration—in particular if an invalid or non-callable handler is passed—the operation fails and returns the error code NmErrc::kInvalidHandler.

Concurrency and Interaction

Regarding thread safety, the interface is specified as not thread-safe [SWS_ANM_01015]. Registration calls must therefore not be made concurrently without protection from multiple threads to the same state context. In the system context, the function complements the base interface [SWS_ANM_01010], which registers a maximum of one notifier without an explicit executor. As an interpretation, it is presumably also true for [SWS_ANM_01015] that only one notifier is active at any time and that a new call replaces a previously registered handler. Question Q-e9a890e004a4f0ea (open)

The function SetNetworkRequestedState serves to request or release a partial network cluster (PNC), a VLAN, or a physical network via header ara/nm/network_handle.h according to [SWS_ANM_01009]. The desired target state networkState of type NetworkStateType is passed as an input parameter. The call is likely executed synchronously, as the interface directly returns a ara::core::Result<void> instead of an asynchronous future object. Question Q-38a98cab4ea55704 (open)

In case of success, the method returns an empty ara::core::Result<void> [SWS_ANM_01009]. If the requested state cannot be set or the network management service is not available, the function reports the specific error code NmErrc::kServiceNotAvailable in the result object [SWS_ANM_01009]. Calling software components must explicitly evaluate this error object in order to react adequately to unavailable services.

With regard to concurrency, the operation is explicitly classified according to the specification as not thread-safe [SWS_ANM_01009]. Therefore, concurrent calls on the same handle must not occur without application-side synchronization to avoid race conditions. Furthermore, declaration with noexcept guarantees that no C++ exceptions escape to the outside [SWS_ANM_01009].

use

The function UnregisterNetworkRequestedStateChangeNotifier belongs to the Adaptive Network Management module (anm) and is declared via the header ara/nm/network_handle.h [SWS_ANM_01013]. Its purpose is to cancel the notifier for changes to the requested network state [SWS_ANM_01013], thereby contributing to the fulfillment of upstream requirement RS_Nm_00051.

The interface expects no input parameters and returns no return value (void) [SWS_ANM_01013]. Interpretation: Since the signature provides no asynchronous result type, the call is likely executed synchronously and the deregistration becomes effective immediately upon return of the function. Question Q-df3005625905440a (open)

Error handling

The function is specified with noexcept [SWS_ANM_01013] and thus throws no exceptions. The specification provides neither error codes nor separate error reactions for the caller.

Concurrency and Limitations

Regarding thread safety, the function is explicitly classified as not thread-safe [SWS_ANM_01013]. Calling software units must therefore ensure through appropriate synchronization measures that deregistration is not executed concurrently with other accesses to the same instance.