classe ara::nm::NetworkHandle

Utilisation et cycle de vie

La classe NetworkHandle fait office d'objet d'accès à un handle réseau adressé via un ara::core::InstanceSpecifier et est prévue pour le State Management [SWS_ANM_01000]. L'instanciation s'effectue par la transmission de l'InstanceSpecifier d'un prototype de port NetworkManagementPortInterface [SWS_ANM_01001]. La classe étant déclarée comme final, elle ne peut pas être utilisée comme classe de base pour des dérivations [SWS_ANM_01000].

Sémantique de déplacement et concurrence

Les objets de cette classe possèdent une sémantique de déplacement pure : le constructeur de copie [SWS_ANM_01005] ainsi que l'opérateur d'affectation par copie [SWS_ANM_01006] sont supprimés (= delete). Les instances peuvent à la place être transférées via le constructeur de déplacement [SWS_ANM_01003] et l'opérateur d'affectation par déplacement [SWS_ANM_01004].

Concernant la sécurité des threads (thread safety), les exigences suivantes s'appliquent :

• Le constructeur avec InstanceSpecifier est thread-safe (thread-safe) [SWS_ANM_01001].
• Pour le constructeur de déplacement, la sécurité des threads est définie de manière spécifique à l'implémentation (implementation-defined) [SWS_ANM_01003].
• Le destructeur [SWS_ANM_01002] et l'affectation par déplacement [SWS_ANM_01004] sont explicitement désignés comme non thread-safe (not thread-safe). Interprétation : aucune sécurité des threads n'étant garantie, le contexte appelant devrait être responsable d'une synchronisation externe si plusieurs threads utilisent le même handle. Question Q-7172baaffab79218 (ouverte)

Gestion des erreurs

L'ensemble des constructeurs, des opérateurs d'affectation ainsi que le destructeur sont déclarés comme noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Aucune exception ni valeur de retour d'erreur n'est prévue dans l'interface de cette classe.

L'alias de type NetworkStateChangeNotifier issu de l'en-tête ara/nm/network_handle.h définit un wrapper de fonction pour les fonctions de rappel lors de changements d'état du réseau [SWS_ANM_01020]. La signature std::function<void(const NetworkStateType&)> reçoit comme paramètre le nouvel état sous forme de référence constante vers NetworkStateType et ne possède aucune valeur de retour [SWS_ANM_01020].

Le notifieur est utilisé lors de la surveillance du Network Management via deux points d'enregistrement :

• Pour signaler l'état effectif du réseau, le notifieur est enregistré au moyen de RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. Alternativement, une surcharge de modèle permet la transmission d'un executor personnalisé, dans le contexte duquel le notifieur est exécuté [SWS_ANM_01015]. Au maximum un seul notifieur peut être actif par instance [SWS_ANM_01010].
• Pour les notifications concernant l'état du réseau demandé, l'enregistrement s'effectue via RegisterNetworkRequestedStateChangeNotifier, au choix directement [SWS_ANM_01012] ou avec indication d'un exécuteur cible [SWS_ANM_01014]. Ici aussi, un seul gestionnaire au maximum est autorisé [SWS_ANM_01012].

En matière de gestion des erreurs, toutes les fonctions d'enregistrement renvoient un ara::core::Result<void> ; si l'enregistrement échoue, l'erreur NmErrc::kInvalidHandler est signalée [SWS_ANM_01010], [SWS_ANM_01012]. Cela devrait se produire en particulier lorsqu'un objet fonctionnel incomplètement initialisé ou vide est transmis. Question Q-04452871df619a94 (ouverte)

En tant que restriction, NetworkStateChangeNotifier est spécifié comme non thread-safe (not thread-safe) [SWS_ANM_01020]. Les fonctions d'enregistrement associées sont également conçues comme non thread-safe [SWS_ANM_01010], [SWS_ANM_01012]. Les appelants doivent donc s'assurer que l'affectation ainsi que l'enregistrement s'effectuent de façon synchronisée ou séquentielle.

L'énumération NetworkStateType représente l'état d'un réseau dans le module anm (Adaptive Network Management) [SWS_ANM_01358]. Elle fait la distinction entre l'état inactif kNoCom = 0 (si tous les réseaux associés ne sont pas à l'état FULL_COM) et l'état actif kFullCom = 1 (lorsque tous les réseaux associés sont FULL_COM) [SWS_ANM_01358].

Le type est largement utilisé dans les interfaces de ara/nm/network_handle.h :

• Interrogation de l'état : la méthode GetNetworkState() renvoie de manière synchrone et thread-safe l'état effectif actuel du réseau sous la forme ara::core::Result<NetworkStateType> [SWS_ANM_01007]. De même, GetNetworkRequestedState() lit de manière thread-safe l'état actuellement demandé pour un PNC, un VLAN ou un réseau physique [SWS_ANM_01008].
• Demande d'état : via SetNetworkRequestedState(NetworkStateType networkState), un état est activement demandé (kFullCom) ou libéré (kNoCom) pour un PNC, un VLAN ou un réseau physique [SWS_ANM_01009]. Cette opération est spécifiée comme non thread-safe [SWS_ANM_01009].
• Notification d'événement : via l'enveloppe de fonction NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>), le type est transmis comme paramètre afin d'informer la logique applicative des changements d'état [SWS_ANM_01020].

Traitement des erreurs : lors de l'interrogation ou de la définition de NetworkStateType via les méthodes mentionnées, le code NmErrc::kServiceNotAvailable peut, en cas d'erreur, être renvoyé dans ara::core::Result [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

Utilisation

La fonction RegisterNetworkRequestedStateChangeNotifier du fichier d'en-tête ara/nm/network_handle.h enregistre une fonction de rappel destinée à notifier les changements d'état du réseau demandé [SWS_ANM_01012]. Un NetworkStateChangeNotifier lui est transmis en tant que paramètre. Au maximum un seul notificateur peut être enregistré pour les modifications de l'état demandé [SWS_ANM_01012]. La fonction est déclarée comme noexcept et renvoie un ara::core::Result<void>.

Gestion des erreurs

Si une erreur survient lors de l'enregistrement, elle est signalée via le ara::core::Result avec le code d'erreur spécifique NmErrc::kInvalidHandler [SWS_ANM_01012]. Interprétation : cette erreur devrait être déclenchée lorsque le notificateur transmis n'est pas valide ou ne peut pas être appelé. Question Q-57a28e90a933e6de (ouverte)

Concurrence et restrictions

La fonction est spécifiée comme non thread-safe (not thread-safe) [SWS_ANM_01012]. Les appelants doivent donc impérativement synchroniser de manière externe les accès parallèles et les tentatives d'enregistrement depuis plusieurs threads.

Interaction

Comme alternative à l'exécution directe, il existe une surcharge de modèle de la fonction [SWS_ANM_01014] qui prend en outre un paramètre executor. Cela permet d'exécuter le notificateur dans un contexte d'exécution explicitement fourni ; cette surcharge n'est pas non plus thread-safe et signale NmErrc::kInvalidHandler en cas d'erreur [SWS_ANM_01014].

La fonction modèle RegisterNetworkRequestedStateChangeNotifier déclarée dans le fichier d'en-tête ara/nm/network_handle.h enregistre un callback de type NetworkStateChangeNotifier afin d'être notifié des changements d'état du réseau demandé [SWS_ANM_01014]. Via le paramètre supplémentaire executor de type ExecutorT&&, le contexte d'exécution souhaité dans lequel ce notificateur doit être exécuté lors de changements d'état est défini. L'appel synchrone pour l'enregistrement du gestionnaire est déclaré comme noexcept et renvoie un ara::core::Result<void> à l'appelant.

Pour la gestion des erreurs, l'interface signale les problèmes via le type de retour ara::core::Result. Si un gestionnaire non valide est transmis, l'opération échoue et la fonction renvoie le code d'erreur spécifique NmErrc::kInvalidHandler [SWS_ANM_01014].

En ce qui concerne la concurrence et les restrictions d'appel, la fonction est explicitement spécifiée comme not thread-safe [SWS_ANM_01014]. Cela signifie que les appelants doivent assurer une synchronisation externe en cas d'accès parallèles à la même instance de handle afin d'éviter les conflits de données.

Dans l'interaction du système, cette fonction constitue une extension de la variante à moins de paramètres [SWS_ANM_01012], laquelle enregistre au maximum un notificateur pour les changements de l'état demandé. Interprétation : étant donné que la spécification de base dans [SWS_ANM_01012] n'autorise au maximum qu'un notificateur, cet appel devrait également occuper le même emplacement de notificateur et écraser un gestionnaire précédemment défini lors d'un nouvel enregistrement. Question Q-5d8c1832558ac15b (ouverte)

Utilisation

La fonction RegisterNetworkStateChangeNotifier sert à enregistrer un notificateur pour l'état effectif du réseau [SWS_ANM_01010]. Elle est déclarée dans l'en-tête ara/nm/network_handle.h et définie en tant que noexcept [SWS_ANM_01010]. Un NetworkStateChangeNotifier notifier est transmis comme paramètre ; le retour a lieu de façon synchrone via ara::core::Result<void> [SWS_ANM_01010]. Il ne peut être enregistré au maximum qu'un seul notificateur pour l'état [SWS_ANM_01010].

Gestion des erreurs

En cas d'erreur, le ara::core::Result renvoie le code d'erreur NmErrc::kInvalidHandler [SWS_ANM_01010]. Cela signale à l'appelant que le gestionnaire transmis n'est pas valide [SWS_ANM_01010].

Concurrence et restrictions

L'interface est expressément spécifiée comme not thread-safe [SWS_ANM_01010]. Les composants appelants doivent par conséquent veiller à ce que les appels de RegisterNetworkStateChangeNotifier ne se fassent pas de manière concurrente sans synchronisation externe. La spécification prévoyant au maximum un notificateur, un appel répété devrait vraisemblablement écraser ou rejeter un enregistrement existant [SWS_ANM_01010]. Question Q-5e3ac4e4d2b33e9f (ouverte)

Interaction

La fonction est directement liée à la surcharge de modèle (template) [SWS_ANM_01015]. Tandis que la fonction de base lie le notificateur sans contexte d'exécution explicite, [SWS_ANM_01015] permet la transmission d'un paramètre supplémentaire ExecutorT&& executor afin de piloter l'exécution du gestionnaire dans un contexte donné [SWS_ANM_01015]. Les deux variantes implémentent des exigences issues de RS_Nm_00051, sont définies dans le même en-tête et partagent la classification not thread-safe ainsi que l'erreur NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

La fonction modèle RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) issue du fichier d'en-tête ara/nm/network_handle.h enregistre une fonction de rappel destinée à surveiller les changements de l'état effectif du réseau. Par rapport à la variante prenant moins de paramètres, cette interface accepte, en plus du notifier de type NetworkStateChangeNotifier, un contexte d'exécution personnalisé executor (ExecutorT&&) par lequel les notifications sont planifiées et traitées de manière asynchrone.

Gestion des erreurs et valeurs de retour

La fonction est déclarée en tant que noexcept et signale le résultat via un ara::core::Result<void> [SWS_ANM_01015]. Si une erreur survient lors de l'enregistrement – en particulier si un gestionnaire non valide ou non appelable est transmis –, l'opération échoue et renvoie le code d'erreur NmErrc::kInvalidHandler.

Concurrence et interaction

En matière de sécurité des threads, l'interface est spécifiée comme not thread-safe [SWS_ANM_01015]. Les appels d'enregistrement ne doivent donc pas avoir lieu de manière concurrente non protégée depuis plusieurs threads sur le même contexte d'état. Au sein du système global, la fonction complète l'interface de base [SWS_ANM_01010], qui enregistre au maximum un notificateur sans exécuteur explicite. En guise d'interprétation, il devrait probablement valoir aussi pour [SWS_ANM_01015] qu'un seul notificateur est actif à la fois et qu'un nouvel appel remplace un gestionnaire précédemment enregistré. Question Q-e9a890e004a4f0ea (ouverte)

La fonction SetNetworkRequestedState sert à demander ou à libérer un cluster de sous-réseau (PNC), un VLAN ou un réseau physique via l'en-tête ara/nm/network_handle.h selon [SWS_ANM_01009]. L'état cible souhaité networkState de type NetworkStateType est transmis en tant que paramètre d'entrée. L'appel devrait être exécuté de manière synchrone, étant donné que l'interface renvoie directement un ara::core::Result<void> au lieu d'un objet Future asynchrone. Question Q-38a98cab4ea55704 (ouverte)

En cas de succès, la méthode renvoie un ara::core::Result<void> vide [SWS_ANM_01009]. Si l'état demandé ne peut pas être défini ou si le service de gestion de réseau n'est pas disponible, la fonction signale le code d'erreur spécifique NmErrc::kServiceNotAvailable dans l'objet de résultat [SWS_ANM_01009]. Les composants logiciels appelants doivent évaluer explicitement cet objet d'erreur afin de réagir de manière adéquate aux services non disponibles.

Concernant la concurrence, l'opération est explicitement classée selon la spécification comme not thread-safe [SWS_ANM_01009]. Par conséquent, des appels simultanés sur le même handle ne doivent pas avoir lieu sans synchronisation côté application, afin d'éviter des conditions de concurrence (race conditions). De plus, la déclaration avec noexcept garantit qu'aucune exception C++ ne s'échappe vers l'extérieur [SWS_ANM_01009].

Utilisation

La fonction UnregisterNetworkRequestedStateChangeNotifier appartient au module de Network Management adaptatif (anm) et est déclarée via l'en-tête ara/nm/network_handle.h [SWS_ANM_01013]. Sa tâche consiste à supprimer le notificateur pour les modifications de l'état réseau demandé [SWS_ANM_01013], contribuant ainsi à la mise en œuvre de l'exigence en amont RS_Nm_00051.

L'interface n'attend aucun paramètre d'entrée et ne fournit aucune valeur de retour (void) [SWS_ANM_01013]. Interprétation : la signature ne prévoyant aucun type de résultat asynchrone, l'appel devrait être exécuté de manière synchrone et le désenregistrement effectif dès le retour de la fonction. Question Q-df3005625905440a (ouverte)

Gestion des erreurs

La fonction est spécifiée avec noexcept [SWS_ANM_01013] et ne lève donc aucune exception. La spécification ne prévoit ni codes d'erreur ni réactions aux erreurs particulières pour l'appelant.

Concurrence et restrictions

En ce qui concerne la sécurité des threads, la fonction est explicitement classée comme not thread-safe [SWS_ANM_01013]. Les entités logicielles appelantes doivent donc s'assurer, par des mesures de synchronisation appropriées, que le désenregistrement n'est pas exécuté de façon concurrente à d'autres accès à la même instance.