class ara::nm::NetworkHandle

Verwendung und Lebenszyklus

Die Klasse NetworkHandle fungiert als Zugriffsobjekt auf einen Netzwerk-Handle, der über einen ara::core::InstanceSpecifier adressiert wird, und ist für das State Management vorgesehen [SWS_ANM_01000]. Die Instanziierung erfolgt über die Übergabe des Instance-Specifiers eines NetworkManagementPortInterface-Port-Prototyps [SWS_ANM_01001]. Da die Klasse als final deklariert ist, kann sie nicht als Basisklasse für Ableitungen genutzt werden [SWS_ANM_01000].

Verschiebesemantik und Nebenläufigkeit

Objekte dieser Klasse besitzen eine reine Verschiebesemantik: Der Kopierkonstruktor [SWS_ANM_01005] sowie der Kopierzuweisungsoperator [SWS_ANM_01006] sind gelöscht (= delete). Instanzen können stattdessen über den Verschiebekonstruktor [SWS_ANM_01003] und den Verschiebezuweisungsoperator [SWS_ANM_01004] übertragen werden.

Hinsichtlich der Thread-Safety gelten folgende Vorgaben:

• Der Konstruktor mit InstanceSpecifier ist threadsicher (thread-safe) [SWS_ANM_01001].
• Für den Verschiebekonstruktor ist die Threadsicherheit implementationsspezifisch definiert (implementation-defined) [SWS_ANM_01003].
• Der Destruktor [SWS_ANM_01002] und die Verschiebezuweisung [SWS_ANM_01004] sind explizit als nicht threadsicher (not thread-safe) ausgewiesen. Interpretation: Da keine Thread-Safety gewährleistet wird, dürfte der aufrufende Kontext für eine externe Synchronisation verantwortlich sein, sofern mehrere Threads denselben Handle nutzen. Frage Q-7172baaffab79218 (offen)

Fehlerbehandlung

Sämtliche Konstruktoren, Zuweisungsoperatoren sowie der Destruktor sind als noexcept deklariert [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Ausnahmen oder Fehlerrückgabewerte sind in dieser Klassenschnittstelle nicht vorgesehen.

Der Typ-Alias NetworkStateChangeNotifier aus dem Header ara/nm/network_handle.h definiert einen Funktionswrapper für Rückruffunktionen bei Netzwerkzustandsänderungen [SWS_ANM_01020]. Die Signatur std::function<void(const NetworkStateType&)> nimmt als Parameter den neuen Zustand als konstante Referenz auf NetworkStateType entgegen und besitzt keinen Rückgabewert [SWS_ANM_01020].

Verwendung findet der Notifier bei der Überwachung des Netzwerkmanagements über zwei Registrierungsstellen:

• Zur Signalisierung des effektiven Netzwerkzustands wird der Notifier mittels RegisterNetworkStateChangeNotifier registriert [SWS_ANM_01010]. Alternativ erlaubt eine Template-Überladung die Übergabe eines benutzerdefinierten executor, in dessen Kontext der Notifier ausgeführt wird [SWS_ANM_01015]. Pro Instanz kann maximal ein Notifier aktiv sein [SWS_ANM_01010].
• Für Benachrichtigungen über den angeforderten Netzwerkzustand erfolgt die Registrierung über RegisterNetworkRequestedStateChangeNotifier, wahlweise direkt [SWS_ANM_01012] oder mit Angabe eines Ziel-Executors [SWS_ANM_01014]. Auch hier ist maximal ein Handler zulässig [SWS_ANM_01012].

Hinsichtlich der Fehlerbehandlung geben alle Registrierungsfunktionen ein ara::core::Result<void> zurück; schlägt die Registrierung fehl, wird der Fehler NmErrc::kInvalidHandler gemeldet [SWS_ANM_01010], [SWS_ANM_01012]. Dies dürfte insbesondere dann auftreten, wenn ein unvollständig initialisiertes oder leeres Funktionsobjekt übergeben wird. Frage Q-04452871df619a94 (offen)

Als Einschränkung ist NetworkStateChangeNotifier als nicht threadsicher (not thread-safe) spezifiziert [SWS_ANM_01020]. Auch die zugehörigen Registrierungsfunktionen sind nicht threadsicher ausgelegt [SWS_ANM_01010], [SWS_ANM_01012]. Aufrufer müssen daher sicherstellen, dass die Zuweisung sowie die Registrierung synchronisiert oder sequenziell erfolgen.

Die Enumeration NetworkStateType repräsentiert den Zustand eines Netzwerks im Modul anm (Adaptive Network Management) [SWS_ANM_01358]. Sie unterscheidet zwischen dem inaktiven Zustand kNoCom = 0 (sofern nicht alle zugeordneten Netze im Zustand FULL_COM sind) und dem aktiven Zustand kFullCom = 1 (wenn alle zugeordneten Netze FULL_COM sind) [SWS_ANM_01358].

Der Typ findet vielseitige Verwendung in den Schnittstellen von ara/nm/network_handle.h:

• Zustandsabfrage: Die Methode GetNetworkState() liefert synchron und threadsicher den aktuellen effektiven Netzwerkzustand als ara::core::Result<NetworkStateType> zurück [SWS_ANM_01007]. Ebenso liest GetNetworkRequestedState() threadsicher den aktuell angeforderten Zustand für ein PNC, VLAN oder physisches Netz aus [SWS_ANM_01008].
• Zustandsanforderung: Über SetNetworkRequestedState(NetworkStateType networkState) wird ein Zustand für ein PNC, ein VLAN oder ein physisches Netz aktiv angefordert (kFullCom) oder freigegeben (kNoCom) [SWS_ANM_01009]. Diese Operation ist als nicht threadsicher spezifiziert [SWS_ANM_01009].
• Ereignisbenachrichtigung: Über den Funktionswrapper NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>) wird der Typ als Parameter übergeben, um Anwendungslogik über Zustandswechsel zu informieren [SWS_ANM_01020].

Fehlerbehandlung: Beim Abfragen oder Setzen von NetworkStateType über die genannten Methoden kann im Fehlerfall der Code NmErrc::kServiceNotAvailable im ara::core::Result zurückgegeben werden [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

Verwendung

Die Funktion RegisterNetworkRequestedStateChangeNotifier aus dem Header ara/nm/network_handle.h registriert eine Callback-Funktion zur Benachrichtigung über Änderungen des angeforderten Netzwerkzustands [SWS_ANM_01012]. Ihr wird als Parameter ein NetworkStateChangeNotifier übergeben. Es kann maximal ein Notifier für Änderungen des angeforderten Zustands registriert werden [SWS_ANM_01012]. Die Funktion ist als noexcept deklariert und liefert ein ara::core::Result<void> zurück.

Fehlerbehandlung

Tritt bei der Registrierung ein Fehler auf, wird dieser über das ara::core::Result mit dem spezifischen Fehlercode NmErrc::kInvalidHandler gemeldet [SWS_ANM_01012]. Interpretation: Dieser Fehler dürfte ausgelöst werden, wenn der übergebene Notifier ungültig oder nicht aufrufbar ist. Frage Q-57a28e90a933e6de (offen)

Nebenläufigkeit und Einschränkungen

Die Funktion ist als nicht threadsicher (not thread-safe) spezifiziert [SWS_ANM_01012]. Aufrufer müssen parallele Zugriffe und Registrierungsversuche aus mehreren Threads daher zwingend extern synchronisieren.

Zusammenspiel

Als Alternative zur direkten Ausführung existiert eine Template-Überladung der Funktion [SWS_ANM_01014], die zusätzlich einen executor-Parameter entgegennimmt. Damit lässt sich der Notifier in einem explizit bereitgestellten Ausführungskontext betreiben; auch diese Überladung ist nicht threadsicher und meldet im Fehlerfall NmErrc::kInvalidHandler [SWS_ANM_01014].

Die im Header ara/nm/network_handle.h deklarierte Template-Funktion RegisterNetworkRequestedStateChangeNotifier registriert einen Callback vom Typ NetworkStateChangeNotifier, um über Zustandsänderungen des angeforderten Netzwerks benachrichtigt zu werden [SWS_ANM_01014]. Über den zusätzlichen Parameter executor vom Typ ExecutorT&& wird der gewünschte Ausführungskontext festgelegt, in welchem dieser Notifier bei Statusänderungen ausgeführt werden soll. Der synchrone Aufruf zur Handler-Registrierung ist als noexcept deklariert und gibt ein ara::core::Result<void> an den Aufrufer zurück.

Zur Fehlerbehandlung signalisiert die Schnittstelle Probleme über den Rückgabetyp ara::core::Result. Falls ein ungültiger Handler übergeben wird, scheitert der Vorgang und die Funktion liefert den spezifischen Fehlercode NmErrc::kInvalidHandler zurück [SWS_ANM_01014].

Hinsichtlich der Nebenläufigkeit und Aufrufeinschränkungen ist die Funktion explizit als not thread-safe spezifiziert [SWS_ANM_01014]. Dies bedeutet, dass Aufrufer bei parallelen Zugriffen auf dieselbe Handle-Instanz für eine externe Synchronisation sorgen müssen, um Datenkonflikte zu vermeiden.

Im Systemzusammenspiel stellt diese Funktion eine Erweiterung der parameterärmeren Variante [SWS_ANM_01012] dar, welche maximal einen Notifier für Änderungen des angeforderten Zustands registriert. Interpretation: Da die Basisspezifikation in [SWS_ANM_01012] maximal einen Notifier zulässt, dürfte auch dieser Aufruf denselben Notifier-Slot belegen und bei erneuter Registrierung einen zuvor gesetzten Handler überschreiben. Frage Q-5d8c1832558ac15b (offen)

Verwendung

Die Funktion RegisterNetworkStateChangeNotifier dient der Registrierung eines Notifiers für den effektiven Netzwerkzustand [SWS_ANM_01010]. Sie ist im Header ara/nm/network_handle.h deklariert und als noexcept definiert [SWS_ANM_01010]. Als Parameter wird ein NetworkStateChangeNotifier notifier übergeben; die Rückgabe erfolgt synchron über ara::core::Result<void> [SWS_ANM_01010]. Es kann maximal ein Notifier für den Zustand registriert werden [SWS_ANM_01010].

Fehlerbehandlung

Im Fehlerfall liefert das ara::core::Result den Fehlercode NmErrc::kInvalidHandler zurück [SWS_ANM_01010]. Dies signalisiert dem Aufrufer, dass der übergebene Handler ungültig ist [SWS_ANM_01010].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist ausdrücklich als not thread-safe spezifiziert [SWS_ANM_01010]. Aufrufende Komponenten müssen daher sicherstellen, dass Aufrufe von RegisterNetworkStateChangeNotifier nicht nebenläufig ohne externe Synchronisation erfolgen. Da die Spezifikation maximal einen Notifier vorsieht, dürfte ein wiederholter Aufruf vermutlich eine bestehende Registrierung überschreiben oder abweisen [SWS_ANM_01010]. Frage Q-5e3ac4e4d2b33e9f (offen)

Zusammenspiel

Die Funktion steht in direktem Zusammenhang mit der Template-Überladung [SWS_ANM_01015]. Während die Basisfunktion den Notifier ohne expliziten Ausführungskontext bindet, erlaubt [SWS_ANM_01015] die Übergabe eines zusätzlichen Parameters ExecutorT&& executor, um die Ausführung des Handlers in einem vorgegebenen Kontext zu steuern [SWS_ANM_01015]. Beide Varianten realisieren Anforderungen aus RS_Nm_00051, sind im selben Header definiert und teilen die Einstufung not thread-safe sowie den Fehler NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

Die Template-Funktion RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) aus dem Header ara/nm/network_handle.h registriert eine Callback-Funktion zur Überwachung von Änderungen des effektiven Netzwerkzustands. Gegenüber der parameterärmeren Variante übernimmt diese Schnittstelle neben dem notifier vom Typ NetworkStateChangeNotifier zusätzlich einen benutzerdefinierten Ausführungskontext executor (ExecutorT&&), über den Benachrichtigungen asynchron disponiert und abgearbeitet werden.

Fehlerbehandlung und Rückgabewerte

Die Funktion ist als noexcept deklariert und signalisiert das Ergebnis über ein ara::core::Result<void> [SWS_ANM_01015]. Tritt bei der Registrierung ein Fehler auf – insbesondere wenn ein ungültiger oder nicht aufrufbarer Handler übergeben wird –, schlägt die Operation fehl und gibt den Fehlercode NmErrc::kInvalidHandler zurück.

Nebenläufigkeit und Zusammenspiel

Hinsichtlich der Thread-Sicherheit ist die Schnittstelle als not thread-safe spezifiziert [SWS_ANM_01015]. Registrierungsaufrufe dürfen daher nicht ungeschützt nebenläufig aus mehreren Threads auf denselben Zustandskontext erfolgen. Im Systemverbund ergänzt die Funktion die Basisschnittstelle [SWS_ANM_01010], welche maximal einen Notifier ohne expliziten Executor registriert. Als Interpretation dürfte vermutlich auch für [SWS_ANM_01015] gelten, dass stets nur ein Notifier aktiv ist und ein Neuaufruf einen zuvor hinterlegten Handler ersetzt. Frage Q-e9a890e004a4f0ea (offen)

Die Funktion SetNetworkRequestedState dient dem Anfordern oder Freigeben eines Teilnetzclusters (PNC), eines VLANs oder eines physischen Netzwerks über den Header ara/nm/network_handle.h gemäß [SWS_ANM_01009]. Als Eingabeparameter wird der gewünschte Zielzustand networkState vom Typ NetworkStateType übergeben. Der Aufruf dürfte synchron ausgeführt werden, da die Schnittstelle direkt ein ara::core::Result<void> anstelle eines asynchronen Future-Objekts zurückliefert. Frage Q-38a98cab4ea55704 (offen)

Im Erfolgsfall liefert die Methode ein leeres ara::core::Result<void> zurück [SWS_ANM_01009]. Kann der angeforderte Zustand nicht gesetzt werden oder steht der Netzwerkmanagement-Dienst nicht bereit, meldet die Funktion den spezifischen Fehlercode NmErrc::kServiceNotAvailable im Ergebnisobjekt [SWS_ANM_01009]. Aufrufende Softwarekomponenten müssen dieses Fehlerobjekt explizit auswerten, um auf nicht verfügbare Dienste adäquat zu reagieren.

In Bezug auf die Nebenläufigkeit ist die Operation gemäß Spezifikation explizit als not thread-safe eingestuft [SWS_ANM_01009]. Daher dürfen gleichzeitige Aufrufe auf demselben Handle nicht ohne anwendungsseitige Synchronisation erfolgen, um Race Conditions zu vermeiden. Durch die Deklaration mit noexcept ist zudem garantiert, dass keine C++-Ausnahmen nach außen dringen [SWS_ANM_01009].

Verwendung

Die Funktion UnregisterNetworkRequestedStateChangeNotifier gehört zum Modul für adaptives Netzwerkmanagement (anm) und wird über den Header ara/nm/network_handle.h deklariert [SWS_ANM_01013]. Ihre Aufgabe besteht darin, den Notifier für Änderungen des angeforderten Netzwerkzustands aufzuheben [SWS_ANM_01013], wodurch sie zur Umsetzung der Upstream-Anforderung RS_Nm_00051 beiträgt.

Die Schnittstelle erwartet keine Übergabeparameter und liefert keinen Rückgabewert (void) [SWS_ANM_01013]. Interpretation: Da die Signatur keinen asynchronen Ergebnistyp vorsieht, dürfte der Aufruf synchron vollzogen werden und die Abmeldung unmittelbar nach Rückkehr der Funktion wirksam sein. Frage Q-df3005625905440a (offen)

Fehlerbehandlung

Die Funktion ist mit noexcept spezifiziert [SWS_ANM_01013] und wirft somit keine Exceptions. Es sind in der Spezifikation weder Fehlercodes noch gesonderte Fehlerreaktionen für den Aufrufer vorgesehen.

Nebenläufigkeit und Einschränkungen

Hinsichtlich der Thread-Sicherheit ist die Funktion explizit als not thread-safe eingestuft [SWS_ANM_01013]. Aufrufende Softwareeinheiten müssen daher durch geeignete Synchronisationsmaßnahmen sicherstellen, dass die Deregistrierung nicht nebenläufig zu anderen Zugriffen auf dieselbe Instanz ausgeführt wird.