klasse ara::nm::NetworkHandle

Gebruik en levenscyclus

De klasse NetworkHandle fungeert als toegangsobject tot een netwerk-handle die via een ara::core::InstanceSpecifier wordt geadresseerd, en is bedoeld voor State Management [SWS_ANM_01000]. De instantiëring vindt plaats via de overdracht van de instance-specifier van een NetworkManagementPortInterface-poortprototype [SWS_ANM_01001]. Aangezien de klasse als final is gedeclareerd, kan zij niet als basisklasse voor afleidingen worden gebruikt [SWS_ANM_01000].

Move-semantiek en gelijktijdigheid

Objecten van deze klasse hebben een zuivere move-semantiek: De copy-constructor [SWS_ANM_01005] en de copy-assignment-operator [SWS_ANM_01006] zijn verwijderd (= delete). Instanties kunnen in plaats daarvan worden overgedragen via de move-constructor [SWS_ANM_01003] en de move-assignment-operator [SWS_ANM_01004].

Met betrekking tot thread-safety gelden de volgende richtlijnen:

• De constructor met InstanceSpecifier is thread-safe (thread-safe) [SWS_ANM_01001].
• Voor de move-constructor is de thread-safety implementatiespecifiek gedefinieerd (implementation-defined) [SWS_ANM_01003].
• De destructor [SWS_ANM_01002] en de move-assignment [SWS_ANM_01004] zijn expliciet als niet thread-safe (not thread-safe) aangemerkt. Interpretatie: Aangezien er geen thread-safety wordt gewaarborgd, is de aanroepende context vermoedelijk verantwoordelijk voor een externe synchronisatie, voor zover meerdere threads dezelfde handle gebruiken. Vraag Q-7172baaffab79218 (open)

Foutafhandeling

Alle constructors, toewijzingsoperatoren en de destructor zijn gedeclareerd als noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Excepties of foutretourwaarden zijn in deze klasse-interface niet voorzien.

De type-alias NetworkStateChangeNotifier uit de header ara/nm/network_handle.h definieert een functiewrapper voor callback-functies bij wijzigingen van de netwerktoestand [SWS_ANM_01020]. De signatuur std::function<void(const NetworkStateType&)> accepteert als parameter de nieuwe toestand als constante referentie naar NetworkStateType en heeft geen retourwaarde [SWS_ANM_01020].

De notifier wordt gebruikt bij de bewaking van het Network Management via twee registratiepunten:

• Voor het signaleren van de effectieve netwerktoestand wordt de notifier geregistreerd via RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. Als alternatief staat een template-overload de overdracht van een door de gebruiker gedefinieerde executor toe, in de context waarvan de notifier wordt uitgevoerd [SWS_ANM_01015]. Per instantie kan maximaal één notifier actief zijn [SWS_ANM_01010].
• Voor notificaties over de aangevraagde netwerktoestand vindt de registratie plaats via RegisterNetworkRequestedStateChangeNotifier, naar keuze direct [SWS_ANM_01012] of met vermelding van een doel-executor [SWS_ANM_01014]. Ook hier is maximaal één handler toegestaan [SWS_ANM_01012].

Wat betreft foutafhandeling retourneren alle registratiefuncties een ara::core::Result<void>; indien de registratie mislukt, wordt de fout NmErrc::kInvalidHandler gemeld [SWS_ANM_01010], [SWS_ANM_01012]. Dit treedt vermoedelijk met name op wanneer een onvolledig geïnitialiseerd of leeg functie-object wordt meegegeven. Vraag Q-04452871df619a94 (open)

Als beperking is NetworkStateChangeNotifier gespecificeerd als niet-thread-safe (not thread-safe) [SWS_ANM_01020]. Ook de bijbehorende registratiefuncties zijn niet-thread-safe ontworpen [SWS_ANM_01010], [SWS_ANM_01012]. Aanroepers moeten er daarom voor zorgen dat zowel de toewijzing als de registratie gesynchroniseerd of sequentieel plaatsvinden.

De enumeratie NetworkStateType representeert de toestand van een netwerk in de module anm (Adaptive Network Management) [SWS_ANM_01358]. Deze maakt onderscheid tussen de inactieve toestand kNoCom = 0 (voor zover niet alle toegewezen netwerken zich in de toestand FULL_COM bevinden) en de actieve toestand kFullCom = 1 (wanneer alle toegewezen netwerken FULL_COM zijn) [SWS_ANM_01358].

Het type kent veelzijdige toepassingen in de interfaces van ara/nm/network_handle.h:

• Toestandsopvraging: De methode GetNetworkState() retourneert synchroon en thread-safe de actuele effectieve netwerktoestand als ara::core::Result<NetworkStateType> [SWS_ANM_01007]. Eveneens leest GetNetworkRequestedState() thread-safe de actueel aangevraagde toestand voor een PNC, VLAN of fysiek netwerk uit [SWS_ANM_01008].
• Toestandsverzoek: Via SetNetworkRequestedState(NetworkStateType networkState) wordt een toestand voor een PNC, een VLAN of een fysiek netwerk actief aangevraagd (kFullCom) of vrijgegeven (kNoCom) [SWS_ANM_01009]. Deze operatie is als niet thread-safe gespecificeerd [SWS_ANM_01009].
• Gebeurtenisnotificatie: Via de functiewrapper NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>) wordt het type als parameter doorgegeven om applicatielogica over toestandsveranderingen te informeren [SWS_ANM_01020].

Foutafhandeling: Bij het opvragen of instellen van NetworkStateType via de genoemde methoden kan in geval van een fout de code NmErrc::kServiceNotAvailable in ara::core::Result worden geretourneerd [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

Gebruik

De functie RegisterNetworkRequestedStateChangeNotifier uit de header ara/nm/network_handle.h registreert een callback-functie voor notificatie over wijzigingen van de aangevraagde netwerktoestand [SWS_ANM_01012]. Haar wordt als parameter een NetworkStateChangeNotifier overgedragen. Er kan maximaal één notifier voor wijzigingen van de aangevraagde toestand worden geregistreerd [SWS_ANM_01012]. De functie is als noexcept gedeclareerd en levert een ara::core::Result<void> terug.

Foutafhandeling

Treedt bij de registratie een fout op, dan wordt deze via het ara::core::Result met de specifieke foutcode NmErrc::kInvalidHandler gemeld [SWS_ANM_01012]. Interpretation: Deze fout wordt vermoedelijk geactiveerd wanneer de overgedragen notifier ongeldig of niet aanroepbaar is. Vraag Q-57a28e90a933e6de (open)

Gelijktijdigheid en beperkingen

De functie is als niet thread-safe (not thread-safe) gespecificeerd [SWS_ANM_01012]. Aanroepers moeten parallelle toegangen en registratiepogingen vanuit meerdere threads daarom dwingend extern synchroniseren.

Samenspel

Als alternatief voor directe uitvoering bestaat er een template-overload van de functie [SWS_ANM_01014], die aanvullend een executor-parameter accepteert. Hiermee kan de notifier in een expliciet ter beschikking gestelde uitvoeringscontext worden gebruikt; ook deze overload is niet thread-safe en meldt in geval van een fout NmErrc::kInvalidHandler [SWS_ANM_01014].

De in header ara/nm/network_handle.h gedeclareerde templatefunctie RegisterNetworkRequestedStateChangeNotifier registreert een callback van het type NetworkStateChangeNotifier om op de hoogte te worden gesteld van toestandswijzigingen van het aangevraagde netwerk [SWS_ANM_01014]. Via de aanvullende parameter executor van het type ExecutorT&& wordt de gewenste uitvoeringscontext vastgelegd waarin deze notifier bij statuswijzigingen moet worden uitgevoerd. De synchrone aanroep voor handlerregistratie is gedeclareerd als noexcept en geeft een ara::core::Result<void> terug aan de aanroeper.

Voor foutafhandeling signaleert de interface problemen via het retourtype ara::core::Result. Indien een ongeldige handler wordt meegegeven, mislukt de bewerking en levert de functie de specifieke foutcode NmErrc::kInvalidHandler op [SWS_ANM_01014].

Wat betreft gelijktijdigheid en aanroepbeperkingen is de functie expliciet gespecificeerd als not thread-safe [SWS_ANM_01014]. Dit betekent dat aanroepers bij parallelle toegangen tot dezelfde handle-instantie moeten zorgen voor externe synchronisatie om dataconflicten te voorkomen.

In de interactie binnen het systeem vormt deze functie een uitbreiding op de parameterarmere variant [SWS_ANM_01012], die maximaal één notifier voor wijzigingen van de aangevraagde toestand registreert. Interpretatie: Aangezien de basisspecificatie in [SWS_ANM_01012] maximaal één notifier toestaat, zal vermoedelijk ook deze aanroep hetzelfde notifier-slot bezetten en bij een hernieuwde registratie een eerder ingestelde handler overschrijven. Vraag Q-5d8c1832558ac15b (open)

Gebruik

De functie RegisterNetworkStateChangeNotifier dient voor de registratie van een notifier voor de effectieve netwerktoestand [SWS_ANM_01010]. Ze is in de header ara/nm/network_handle.h gedeclareerd en als noexcept gedefinieerd [SWS_ANM_01010]. Als parameter wordt een NetworkStateChangeNotifier notifier overgedragen; de teruggave geschiedt synchroon via ara::core::Result<void> [SWS_ANM_01010]. Er kan maximaal één notifier voor de toestand worden geregistreerd [SWS_ANM_01010].

Foutafhandeling

In geval van een fout levert het ara::core::Result de foutcode NmErrc::kInvalidHandler terug [SWS_ANM_01010]. Dit signaleert aan de aanroeper dat de overgedragen handler ongeldig is [SWS_ANM_01010].

Gelijktijdigheid en beperkingen

De interface is uitdrukkelijk als not thread-safe gespecificeerd [SWS_ANM_01010]. Aanroepende componenten moeten er daarom voor zorgen dat aanroepen van RegisterNetworkStateChangeNotifier niet gelijktijdig zonder externe synchronisatie plaatsvinden. Aangezien de specificatie maximaal één notifier voorziet, zal een herhaalde aanroep vermoedelijk een bestaande registratie overschrijven of afwijzen [SWS_ANM_01010]. Vraag Q-5e3ac4e4d2b33e9f (open)

Samenspel

De functie staat in direct verband met de template-overbelasting [SWS_ANM_01015]. Terwijl de basisfunctie de notifier zonder expliciete uitvoeringscontext bindt, staat [SWS_ANM_01015] de overdracht van een aanvullende parameter ExecutorT&& executor toe om de uitvoering van de handler in een vooraf bepaalde context te sturen [SWS_ANM_01015]. Beide varianten implementeren eisen uit RS_Nm_00051, zijn in dezelfde header gedefinieerd en delen de classificatie not thread-safe evenals de fout NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

De templatefunctie RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) uit de header ara/nm/network_handle.h registreert een callbackfunctie voor het monitoren van wijzigingen van de effectieve netwerktoestand. Ten opzichte van de parameterarmere variant accepteert deze interface naast de notifier van het type NetworkStateChangeNotifier aanvullend een door de gebruiker gedefinieerde uitvoeringscontext executor (ExecutorT&&), waarmee meldingen asynchroon worden ingepland en verwerkt.

Foutafhandeling en retourwaarden

De functie is gedeclareerd als noexcept en signaleert het resultaat via een ara::core::Result<void> [SWS_ANM_01015]. Als er bij de registratie een fout optreedt – in het bijzonder wanneer een ongeldige of niet-aanroepbare handler wordt meegegeven –, mislukt de bewerking en geeft deze de foutcode NmErrc::kInvalidHandler terug.

Gelijktijdigheid en wisselwerking

Wat betreft thread-safety is de interface gespecificeerd als not thread-safe [SWS_ANM_01015]. Registratieaanroepen mogen daarom niet onbeschermd gelijktijdig vanuit meerdere threads op dezelfde toestandscontext plaatsvinden. In het systeemverband vult de functie de basisinterface [SWS_ANM_01010] aan, die maximaal één notifier zonder expliciete executor registreert. Als interpretatie geldt vermoedelijk ook voor [SWS_ANM_01015] dat er steeds slechts één notifier actief is en dat een nieuwe aanroep een eerder ingestelde handler vervangt. Vraag Q-e9a890e004a4f0ea (open)

De functie SetNetworkRequestedState dient voor het aanvragen of vrijgeven van een deelnetwerkcluster (PNC), een VLAN of een fysiek netwerk via de header ara/nm/network_handle.h conform [SWS_ANM_01009]. Als invoerparameter wordt de gewenste doeltoestand networkState van het type NetworkStateType overgedragen. De aanroep wordt vermoedelijk synchroon uitgevoerd, aangezien de interface direct een ara::core::Result<void> in plaats van een asynchroon Future-object retourneert. Vraag Q-38a98cab4ea55704 (open)

Bij succes retourneert de methode een lege ara::core::Result<void> [SWS_ANM_01009]. Als de aangevraagde toestand niet kan worden ingesteld of als de netwerkmanagementdienst niet gereed is, meldt de functie de specifieke foutcode NmErrc::kServiceNotAvailable in het resultaatobject [SWS_ANM_01009]. Aanroepende softwarecomponenten moeten dit foutobject expliciet evalueren om adequaat te reageren op niet-beschikbare diensten.

Met betrekking tot de gelijktijdigheid is de bewerking conform de specificatie expliciet geclassificeerd als not thread-safe [SWS_ANM_01009]. Daarom mogen gelijktijdige aanroepen op dezelfde handle niet zonder synchronisatie aan applicatiezijde plaatsvinden, om race conditions te vermijden. Door de declaratie met noexcept is bovendien gegarandeerd dat er geen C++-excepties naar buiten treden [SWS_ANM_01009].

Gebruik

De functie UnregisterNetworkRequestedStateChangeNotifier behoort tot de module voor adaptief netwerkbeheer (anm) en wordt gedeclareerd via header ara/nm/network_handle.h [SWS_ANM_01013]. Haar taak bestaat erin de notifier voor wijzigingen van de aangevraagde netwerktoestand in te trekken [SWS_ANM_01013], waardoor zij bijdraagt aan de implementatie van de upstream-eis RS_Nm_00051.

De interface verwacht geen overdrachtsparameters en levert geen retourwaarde op (void) [SWS_ANM_01013]. Interpretatie: Aangezien de signatuur niet voorziet in een asynchroon resultaattype, wordt de aanroep vermoedelijk synchroon uitgevoerd en is de afmelding direct na terugkeer van de functie van kracht. Vraag Q-df3005625905440a (open)

Foutafhandeling

De functie is gespecificeerd met noexcept [SWS_ANM_01013] en genereert zodoende geen exceptions. In de specificatie zijn noch foutcodes noch afzonderlijke foutreacties voor de aanroeper voorzien.

Gelijktijdigheid en beperkingen

Wat betreft de thread-safety is de functie expliciet geclassificeerd als not thread-safe [SWS_ANM_01013]. Aanroepende software-eenheden moeten daarom door passende synchronisatiemaatregelen waarborgen dat de deregistratie niet gelijktijdig met andere toegangen tot dezelfde instantie wordt uitgevoerd.