clase ara::nm::NetworkHandle

Uso y ciclo de vida

La clase NetworkHandle actúa como objeto de acceso a un identificador de red direccionado a través de un ara::core::InstanceSpecifier y está prevista para State Management [SWS_ANM_01000]. La instanciación se realiza mediante el paso del InstanceSpecifier de un prototipo de puerto NetworkManagementPortInterface [SWS_ANM_01001]. Dado que la clase está declarada como final, no se puede utilizar como clase base para derivaciones [SWS_ANM_01000].

Semántica de movimiento y concurrencia

Los objetos de esta clase poseen una semántica pura de movimiento: el constructor de copia [SWS_ANM_01005] y el operador de asignación por copia [SWS_ANM_01006] están eliminados (= delete). En su lugar, las instancias se pueden transferir mediante el constructor de movimiento [SWS_ANM_01003] y el operador de asignación por movimiento [SWS_ANM_01004].

En lo relativo a la seguridad para subprocesos rigen las siguientes especificaciones:

• El constructor con InstanceSpecifier es seguro para subprocesos (thread-safe) [SWS_ANM_01001].
• Para el constructor de movimiento, la seguridad para subprocesos está definida de forma específica de la implementación (implementation-defined) [SWS_ANM_01003].
• El destructor [SWS_ANM_01002] y la asignación por movimiento [SWS_ANM_01004] están designados explícitamente como no seguros para subprocesos (not thread-safe). Interpretación: Dado que no se garantiza la seguridad para subprocesos, es probable que el contexto llamador sea responsable de una sincronización externa en caso de que varios subprocesos utilicen el mismo identificador. Pregunta Q-7172baaffab79218 (abierta)

Manejo de errores

Todos los constructores, operadores de asignación y el destructor están declarados como noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. En esta interfaz de clase no se contemplan excepciones ni valores de retorno de error.

El alias de tipo NetworkStateChangeNotifier de la cabecera ara/nm/network_handle.h define un contenedor de función para funciones de retrollamada ante cambios de estado de la red [SWS_ANM_01020]. La signatura std::function<void(const NetworkStateType&)> toma como parámetro el nuevo estado como referencia constante a NetworkStateType y no tiene valor de retorno [SWS_ANM_01020].

El notificador se utiliza en la monitorización del Network Management a través de dos puntos de registro:

• Para la señalización del estado efectivo de la red, el notificador se registra mediante RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. Como alternativa, una sobrecarga de plantilla permite la transferencia de un executor personalizado, en cuyo contexto se ejecuta el notificador [SWS_ANM_01015]. Solo puede haber activo un máximo de un notificador por instancia [SWS_ANM_01010].
• Para las notificaciones sobre el estado solicitado de la red, el registro se realiza mediante RegisterNetworkRequestedStateChangeNotifier, opcionalmente de forma directa [SWS_ANM_01012] o especificando un ejecutor de destino [SWS_ANM_01014]. Aquí también se permite un máximo de un controlador [SWS_ANM_01012].

En cuanto al tratamiento de errores, todas las funciones de registro devuelven un ara::core::Result<void>; si el registro falla, se notifica el error NmErrc::kInvalidHandler [SWS_ANM_01010], [SWS_ANM_01012]. Es de prever que esto ocurra en particular cuando se transfiere un objeto de función incompletamente inicializado o vacío. Pregunta Q-04452871df619a94 (abierta)

Como restricción, NetworkStateChangeNotifier está especificado como no seguro para subprocesos (not thread-safe) [SWS_ANM_01020]. Las funciones de registro correspondientes tampoco están diseñadas para ser seguras para subprocesos [SWS_ANM_01010], [SWS_ANM_01012]. Por lo tanto, los llamantes deben asegurarse de que la asignación así como el registro se efectúen de forma sincronizada o secuencial.

La enumeración NetworkStateType representa el estado de una red en el módulo anm (Adaptive Network Management) [SWS_ANM_01358]. Distingue entre el estado inactivo kNoCom = 0 (siempre que no todas las redes asignadas estén en el estado FULL_COM) y el estado activo kFullCom = 1 (cuando todas las redes asignadas son FULL_COM) [SWS_ANM_01358].

El tipo encuentra múltiples usos en las interfaces de ara/nm/network_handle.h:

• Consulta de estado: El método GetNetworkState() devuelve de forma síncrona y segura para subprocesos el estado de red efectivo actual como ara::core::Result<NetworkStateType> [SWS_ANM_01007]. Asimismo, GetNetworkRequestedState() lee de forma segura para subprocesos el estado actualmente solicitado para un PNC, VLAN o red física [SWS_ANM_01008].
• Solicitud de estado: Mediante SetNetworkRequestedState(NetworkStateType networkState) se solicita activamente (kFullCom) o se libera (kNoCom) un estado para un PNC, una VLAN o una red física [SWS_ANM_01009]. Esta operación está especificada como no segura para subprocesos [SWS_ANM_01009].
• Notificación de eventos: Mediante la función envoltorio NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>) se pasa el tipo como parámetro para informar a la lógica de aplicación sobre cambios de estado [SWS_ANM_01020].

Tratamiento de errores: Al consultar o establecer NetworkStateType mediante los métodos mencionados, en caso de error se puede devolver el código NmErrc::kServiceNotAvailable en ara::core::Result [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

usar

La función RegisterNetworkRequestedStateChangeNotifier del encabezado ara/nm/network_handle.h registra una función de retrollamada para la notificación sobre cambios del estado de red solicitado [SWS_ANM_01012]. Se le pasa como parámetro un NetworkStateChangeNotifier. Se puede registrar como máximo un notificador para cambios del estado solicitado [SWS_ANM_01012]. La función está declarada como noexcept y devuelve un ara::core::Result<void>.

Manejo de errores

Si se produce un error durante el registro, este se notifica a través del ara::core::Result con el código de error específico NmErrc::kInvalidHandler [SWS_ANM_01012]. Interpretación: es previsible que este error se desencadene si el notificador proporcionado no es válido o no es invocable. Pregunta Q-57a28e90a933e6de (abierta)

Concurrencia y restricciones

La función está especificada como no segura para subprocesos (not thread-safe) [SWS_ANM_01012]. Por lo tanto, los llamadores deben sincronizar externamente de forma obligatoria los accesos paralelos y los intentos de registro desde múltiples subprocesos.

Interacción

Como alternativa a la ejecución directa, existe una sobrecarga de plantilla de la función [SWS_ANM_01014] que acepta adicionalmente un parámetro executor. Esto permite operar el notificador en un contexto de ejecución proporcionado explícitamente; esta sobrecarga tampoco es segura para subprocesos y notifica NmErrc::kInvalidHandler en caso de error [SWS_ANM_01014].

La función de plantilla RegisterNetworkRequestedStateChangeNotifier, declarada en el encabezado ara/nm/network_handle.h, registra una retrollamada del tipo NetworkStateChangeNotifier para recibir notificaciones sobre cambios de estado de la red solicitada [SWS_ANM_01014]. A través del parámetro adicional executor del tipo ExecutorT&&, se define el contexto de ejecución deseado en el que se debe ejecutar dicho notificador ante cambios de estado. La llamada síncrona para el registro del manejador está declarada como noexcept y devuelve un ara::core::Result<void> al llamador.

Para el tratamiento de errores, la interfaz señaliza los problemas mediante el tipo de retorno ara::core::Result. Si se pasa un manejador no válido, la operación falla y la función devuelve el código de error específico NmErrc::kInvalidHandler [SWS_ANM_01014].

En lo relativo a la concurrencia y a las restricciones de llamada, la función está especificada explícitamente como not thread-safe [SWS_ANM_01014]. Esto significa que los llamadores deben garantizar una sincronización externa ante accesos paralelos a la misma instancia de identificador con el fin de evitar conflictos de datos.

En la interacción del sistema, esta función representa una ampliación de la variante con menos parámetros [SWS_ANM_01012], la cual registra como máximo un notificador para cambios del estado solicitado. Interpretación: dado que la especificación base en [SWS_ANM_01012] admite como máximo un notificador, es probable que esta llamada ocupe también la misma ranura de notificador y que, en caso de un nuevo registro, sobrescriba un manejador establecido previamente. Pregunta Q-5d8c1832558ac15b (abierta)

usar

La función RegisterNetworkStateChangeNotifier sirve para registrar un notificador del estado efectivo de la red [SWS_ANM_01010]. Está declarada en el encabezado ara/nm/network_handle.h y definida como noexcept [SWS_ANM_01010]. Como parámetro se pasa un NetworkStateChangeNotifier notifier; el retorno se realiza de forma síncrona mediante ara::core::Result<void> [SWS_ANM_01010]. Se puede registrar como máximo un notificador para el estado [SWS_ANM_01010].

Manejo de errores

En caso de error, el ara::core::Result devuelve el código de error NmErrc::kInvalidHandler [SWS_ANM_01010]. Esto indica al llamador que el manejador pasado no es válido [SWS_ANM_01010].

Concurrencia y restricciones

La interfaz está especificada expresamente como not thread-safe [SWS_ANM_01010]. Por tanto, los componentes llamadores deben asegurarse de que las llamadas a RegisterNetworkStateChangeNotifier no se realicen de forma concurrente sin sincronización externa. Dado que la especificación contempla como máximo un notificador, es probable que una llamada reiterada sobrescriba o rechace un registro existente [SWS_ANM_01010]. Pregunta Q-5e3ac4e4d2b33e9f (abierta)

Interacción

La función está directamente relacionada con la sobrecarga de plantilla [SWS_ANM_01015]. Mientras que la función base vincula el notificador sin un contexto de ejecución explícito, [SWS_ANM_01015] permite pasar un parámetro adicional ExecutorT&& executor para controlar la ejecución del manejador en un contexto predeterminado [SWS_ANM_01015]. Ambas variantes implementan requisitos de RS_Nm_00051, están definidas en el mismo encabezado y comparten la clasificación de not thread-safe, así como el error NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

La función de plantilla RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) del encabezado ara/nm/network_handle.h registra una función de retrollamada para monitorizar cambios del estado efectivo de la red. Frente a la variante con menos parámetros, esta interfaz asume, además del notifier de tipo NetworkStateChangeNotifier, un contexto de ejecución personalizado executor (ExecutorT&&) a través del cual se planifican y procesan las notificaciones de manera asíncrona.

Tratamiento de errores y valores de retorno

La función está declarada como noexcept y señaliza el resultado a través de un ara::core::Result<void> [SWS_ANM_01015]. Si ocurre un error durante el registro —en particular si se pasa un manejador no válido o no invocable—, la operación falla y devuelve el código de error NmErrc::kInvalidHandler.

Concurrencia e interacción

En cuanto a la seguridad de subprocesos, la interfaz está especificada como not thread-safe [SWS_ANM_01015]. Por tanto, las llamadas de registro no deben realizarse de forma concurrente y desprotegida desde varios subprocesos sobre el mismo contexto de estado. En el conjunto del sistema, la función complementa a la interfaz base [SWS_ANM_01010], la cual registra como máximo un notificador sin ejecutor explícito. Como interpretación, es de presumir que también para [SWS_ANM_01015] se aplique que siempre haya un solo notificador activo y que una nueva llamada reemplace al manejador almacenado previamente. Pregunta Q-e9a890e004a4f0ea (abierta)

La función SetNetworkRequestedState sirve para solicitar o liberar un clúster de subred (PNC), una VLAN o una red física a través de la cabecera ara/nm/network_handle.h conforme a [SWS_ANM_01009]. Como parámetro de entrada se transfiere el estado objetivo deseado networkState del tipo NetworkStateType. Es de suponer que la llamada se ejecuta de forma síncrona, ya que la interfaz devuelve directamente un ara::core::Result<void> en lugar de un objeto future asíncrono. Pregunta Q-38a98cab4ea55704 (abierta)

En caso de éxito, el método devuelve un ara::core::Result<void> vacío [SWS_ANM_01009]. Si no se puede establecer el estado solicitado o el servicio de gestión de red no está disponible, la función notifica el código de error específico NmErrc::kServiceNotAvailable en el objeto de resultado [SWS_ANM_01009]. Los componentes de software llamadores deben evaluar explícitamente este objeto de error para reaccionar adecuadamente ante servicios no disponibles.

En relación con la concurrencia, la operación está catalogada explícitamente como not thread-safe según la especificación [SWS_ANM_01009]. Por lo tanto, no deben producirse llamadas simultáneas sobre el mismo manejador sin sincronización en la aplicación, con el fin de evitar condiciones de carrera. Además, gracias a la declaración con noexcept, se garantiza que no trascienda ninguna excepción de C++ al exterior [SWS_ANM_01009].

usar

La función UnregisterNetworkRequestedStateChangeNotifier pertenece al módulo de gestión de red adaptativa (anm) y se declara a través de la cabecera ara/nm/network_handle.h [SWS_ANM_01013]. Su cometido consiste en anular el notificador para cambios del estado de red solicitado [SWS_ANM_01013], contribuyendo así a la implementación del requisito upstream RS_Nm_00051.

La interfaz no espera parámetros de entrada y no proporciona ningún valor de retorno (void) [SWS_ANM_01013]. Interpretación: Dado que la firma no contempla ningún tipo de resultado asíncrono, es probable que la llamada se efectúe de forma síncrona y que la cancelación del registro sea efectiva inmediatamente después del retorno de la función. Pregunta Q-df3005625905440a (abierta)

Manejo de errores

La función está especificada con noexcept [SWS_ANM_01013] y, por lo tanto, no lanza excepciones. En la especificación no se contemplan códigos de error ni reacciones de error particulares para el llamador.

Concurrencia y restricciones

En cuanto a la seguridad para subprocesos, la función está catalogada explícitamente como not thread-safe [SWS_ANM_01013]. Por lo tanto, las unidades de software llamadoras deben asegurarse, mediante medidas de sincronización adecuadas, de que la cancelación del registro no se ejecute de forma concurrente con otros accesos a la misma instancia.