classe ara::nm::NetworkHandle

Utilização e ciclo de vida

A classe NetworkHandle atua como objeto de acesso a um handle de rede, que é endereçado através de um ara::core::InstanceSpecifier, e está prevista para o State Management [SWS_ANM_01000]. A instanciação ocorre por meio da passagem do instance specifier de um protótipo de porta NetworkManagementPortInterface [SWS_ANM_01001]. Como a classe está declarada como final, ela não pode ser utilizada como classe base para derivações [SWS_ANM_01000].

Semântica de movimento e concorrência

Objetos desta classe possuem uma semântica puramente de movimento: o construtor de cópia [SWS_ANM_01005] e o operador de atribuição por cópia [SWS_ANM_01006] estão excluídos (= delete). Em vez disso, instâncias podem ser transferidas através do construtor de movimento [SWS_ANM_01003] e do operador de atribuição por movimento [SWS_ANM_01004].

No que diz respeito à thread safety, aplicam-se os seguintes requisitos:

• O construtor com InstanceSpecifier é seguro para threads (thread-safe) [SWS_ANM_01001].
• Para o construtor de movimento, a segurança para threads está definida como específica da implementação (implementation-defined) [SWS_ANM_01003].
• O destrutor [SWS_ANM_01002] e a atribuição por movimento [SWS_ANM_01004] são explicitamente indicados como não thread-safe (not thread-safe). Interpretação: Como nenhuma thread-safety é garantida, o contexto chamador provavelmente é responsável por uma sincronização externa, desde que várias threads utilizem o mesmo handle. Pergunta Q-7172baaffab79218 (aberta)

Tratamento de erros

Todos os construtores, operadores de atribuição e o destrutor são declarados como noexcept [SWS_ANM_01001], [SWS_ANM_01002], [SWS_ANM_01003], [SWS_ANM_01004]. Não estão previstas exceções ou valores de retorno de erro nesta interface de classe.

O alias de tipo NetworkStateChangeNotifier do cabeçalho ara/nm/network_handle.h define um wrapper de função para funções de callback em caso de alterações de estado da rede [SWS_ANM_01020]. A assinatura std::function<void(const NetworkStateType&)> recebe como parâmetro o novo estado sob a forma de referência constante para NetworkStateType e não possui valor de retorno [SWS_ANM_01020].

O notificador é utilizado na monitorização do Network Management através de dois pontos de registo:

• Para sinalização do estado efetivo da rede, o notificador é registado por meio de RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. Em alternativa, uma sobrecarga de template permite a passagem de um executor personalizado, em cujo contexto o notificador é executado [SWS_ANM_01015]. Por instância, pode estar ativo no máximo um notificador [SWS_ANM_01010].
• Para notificações sobre o estado de rede solicitado, o registo ocorre através de RegisterNetworkRequestedStateChangeNotifier, opcionalmente de forma direta [SWS_ANM_01012] ou com especificação de um executor de destino [SWS_ANM_01014]. Também aqui é permitido no máximo um handler [SWS_ANM_01012].

No que diz respeito ao tratamento de erros, todas as funções de registo retornam um ara::core::Result<void>; se o registo falhar, é reportado o erro NmErrc::kInvalidHandler [SWS_ANM_01010], [SWS_ANM_01012]. Isto deverá ocorrer sobretudo quando é passado um objeto de função incompletamente inicializado ou vazio. Pergunta Q-04452871df619a94 (aberta)

Como restrição, NetworkStateChangeNotifier está especificado como não sendo seguro para threads (not thread-safe) [SWS_ANM_01020]. As funções de registo associadas também não foram concebidas para serem seguras para threads [SWS_ANM_01010], [SWS_ANM_01012]. Os chamadores devem, portanto, assegurar que tanto a atribuição como o registo ocorram de forma sincronizada ou sequencial.

A enumeração NetworkStateType representa o estado de uma rede no módulo anm (Adaptive Network Management) [SWS_ANM_01358]. Ela distingue entre o estado inativo kNoCom = 0 (desde que nem todas as redes atribuídas estejam no estado FULL_COM) e o estado ativo kFullCom = 1 (quando todas as redes atribuídas estão em FULL_COM) [SWS_ANM_01358].

O tipo encontra uso versátil nas interfaces de ara/nm/network_handle.h:

• Consulta de estado: O método GetNetworkState() retorna de forma síncrona e thread-safe o estado de rede efetivo atual como ara::core::Result<NetworkStateType> [SWS_ANM_01007]. Da mesma forma, GetNetworkRequestedState() lê de forma thread-safe o estado atualmente solicitado para uma PNC, VLAN ou rede física [SWS_ANM_01008].
• Solicitação de estado: Através de SetNetworkRequestedState(NetworkStateType networkState), um estado para uma PNC, uma VLAN ou uma rede física é ativamente solicitado (kFullCom) ou liberado (kNoCom) [SWS_ANM_01009]. Esta operação é especificada como não thread-safe [SWS_ANM_01009].
• Notificação de eventos: Através do wrapper de função NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>), o tipo é passado como parâmetro para informar a lógica da aplicação sobre transições de estado [SWS_ANM_01020].

Tratamento de erros: Ao consultar ou definir NetworkStateType através dos métodos mencionados, em caso de erro o código NmErrc::kServiceNotAvailable pode ser retornado no ara::core::Result [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

usar

A função RegisterNetworkRequestedStateChangeNotifier do cabeçalho ara/nm/network_handle.h registra uma função de callback para notificação sobre alterações do estado de rede solicitado [SWS_ANM_01012]. É-lhe passado como parâmetro um NetworkStateChangeNotifier. Pode ser registrado no máximo um notificador para alterações do estado solicitado [SWS_ANM_01012]. A função está declarada como noexcept e retorna um ara::core::Result<void>.

Tratamento de erros

Se ocorrer um erro durante o registro, este é reportado através do ara::core::Result com o código de erro específico NmErrc::kInvalidHandler [SWS_ANM_01012]. Interpretação: este erro deverá ser acionado se o notificador passado for inválido ou não chamável. Pergunta Q-57a28e90a933e6de (aberta)

Simultaneidade e restrições

A função está especificada como não segura para threads (not thread-safe) [SWS_ANM_01012]. Por conseguinte, os chamadores devem obrigatoriamente sincronizar de forma externa acessos paralelos e tentativas de registro a partir de múltiplas threads.

Interação

Como alternativa à execução direta, existe uma sobrecarga de template da função [SWS_ANM_01014], que aceita adicionalmente um parâmetro executor. Com isso, o notificador pode ser executado em um contexto de execução explicitamente fornecido; esta sobrecarga também não é segura para threads e reporta em caso de erro NmErrc::kInvalidHandler [SWS_ANM_01014].

A função de template RegisterNetworkRequestedStateChangeNotifier declarada no cabeçalho ara/nm/network_handle.h registra um callback do tipo NetworkStateChangeNotifier para ser notificado sobre alterações de estado da rede solicitada [SWS_ANM_01014]. Através do parâmetro adicional executor do tipo ExecutorT&&, define-se o contexto de execução desejado no qual este notificador deve ser executado em alterações de status. A chamada síncrona para o registro do handler está declarada como noexcept e retorna um ara::core::Result<void> para o chamador.

Para o tratamento de erros, a interface sinaliza problemas através do tipo de retorno ara::core::Result. Se for passado um handler inválido, a operação falha e a função retorna o código de erro específico NmErrc::kInvalidHandler [SWS_ANM_01014].

No que diz respeito à concorrência e às restrições de chamada, a função é explicitamente especificada como not thread-safe [SWS_ANM_01014]. Isto significa que os chamadores devem providenciar sincronização externa em caso de acessos paralelos à mesma instância de handle, a fim de evitar conflitos de dados.

Na interação do sistema, esta função representa uma extensão da variante com menos parâmetros [SWS_ANM_01012], a qual registra no máximo um notificador para alterações do estado solicitado. Interpretação: como a especificação básica em [SWS_ANM_01012] permite no máximo um notificador, esta chamada também deverá ocupar o mesmo slot de notificador e sobrescrever um handler anteriormente definido em caso de novo registro. Pergunta Q-5d8c1832558ac15b (aberta)

usar

A função RegisterNetworkStateChangeNotifier serve para registrar um notificador para o estado efetivo da rede [SWS_ANM_01010]. Ela é declarada no cabeçalho ara/nm/network_handle.h e definida como noexcept [SWS_ANM_01010]. Um NetworkStateChangeNotifier notifier é passado como parâmetro; o retorno ocorre de forma síncrona via ara::core::Result<void> [SWS_ANM_01010]. No máximo um notificador pode ser registrado para o estado [SWS_ANM_01010].

Tratamento de erros

Em caso de erro, o ara::core::Result retorna o código de erro NmErrc::kInvalidHandler [SWS_ANM_01010]. Isso sinaliza ao chamador que o manipulador passado é inválido [SWS_ANM_01010].

Simultaneidade e restrições

A interface é expressamente especificada como not thread-safe [SWS_ANM_01010]. Os componentes chamadores devem, portanto, assegurar que chamadas de RegisterNetworkStateChangeNotifier não ocorram de forma concorrente sem sincronização externa. Como a especificação prevê no máximo um notificador, uma chamada repetida provavelmente sobrescreverá ou rejeitará um registro existente [SWS_ANM_01010]. Pergunta Q-5e3ac4e4d2b33e9f (aberta)

Interação

A função está diretamente relacionada com a sobrecarga de template [SWS_ANM_01015]. Enquanto a função básica vincula o notificador sem contexto de execução explícito, [SWS_ANM_01015] permite a passagem de um parâmetro adicional ExecutorT&& executor para controlar a execução do handler em um contexto predefinido [SWS_ANM_01015]. Ambas as variantes implementam requisitos de RS_Nm_00051, estão definidas no mesmo cabeçalho e compartilham a classificação not thread-safe bem como o erro NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

A função de template RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) do cabeçalho ara/nm/network_handle.h registra uma função de callback para monitorar alterações do estado efetivo de rede. Em comparação com a variante de menos parâmetros, esta interface aceita, além do notifier do tipo NetworkStateChangeNotifier, adicionalmente um contexto de execução executor definido pelo usuário (ExecutorT&&), através do qual notificações são escalonadas e processadas de forma assíncrona.

Tratamento de erros e valores de retorno

A função está declarada como noexcept e sinaliza o resultado através de um ara::core::Result<void> [SWS_ANM_01015]. Se ocorrer um erro durante o registro – especialmente se for passado um handler inválido ou não chamável –, a operação falha e retorna o código de erro NmErrc::kInvalidHandler.

Concorrência e interação

No que diz respeito à segurança de threads, a interface está especificada como not thread-safe [SWS_ANM_01015]. As chamadas de registro não devem, portanto, ocorrer de forma concorrente desprotegida a partir de múltiplas threads para o mesmo contexto de estado. No conjunto do sistema, a função complementa a interface básica [SWS_ANM_01010], a qual registra no máximo um notificador sem executor explícito. Como interpretação, provavelmente também se aplica a [SWS_ANM_01015] que apenas um notificador está ativo a qualquer momento e uma nova chamada substitui um handler anteriormente configurado. Pergunta Q-e9a890e004a4f0ea (aberta)

A função SetNetworkRequestedState serve para solicitar ou liberar um cluster de sub-rede (PNC), uma VLAN ou uma rede física através do cabeçalho ara/nm/network_handle.h conforme [SWS_ANM_01009]. Como parâmetro de entrada, é passado o estado de destino desejado networkState do tipo NetworkStateType. A chamada deve ser executada de forma síncrona, já que a interface retorna diretamente um ara::core::Result<void> em vez de um objeto Future assíncrono. Pergunta Q-38a98cab4ea55704 (aberta)

Em caso de sucesso, o método retorna um ara::core::Result<void> vazio [SWS_ANM_01009]. Se o estado solicitado não puder ser definido ou se o serviço de gerenciamento de rede não estiver disponível, a função relata o código de erro específico NmErrc::kServiceNotAvailable no objeto de resultado [SWS_ANM_01009]. Os componentes de software chamadores devem avaliar esse objeto de erro explicitamente para reagir adequadamente a serviços não disponíveis.

Em relação à concorrência, a operação é explicitamente classificada como not thread-safe de acordo com a especificação [SWS_ANM_01009]. Portanto, chamadas simultâneas no mesmo handle não devem ocorrer sem sincronização pelo lado da aplicação, a fim de evitar race conditions. Devido à declaração com noexcept, garante-se também que nenhuma exceção C++ escape para o exterior [SWS_ANM_01009].

usar

A função UnregisterNetworkRequestedStateChangeNotifier pertence ao módulo para gerenciamento adaptativo de rede (anm) e é declarada através do cabeçalho ara/nm/network_handle.h [SWS_ANM_01013]. Sua função consiste em cancelar o notificador para alterações do estado de rede solicitado [SWS_ANM_01013], contribuindo assim para a implementação do requisito upstream RS_Nm_00051.

A interface não espera parâmetros de entrada e não fornece valor de retorno (void) [SWS_ANM_01013]. Interpretação: Como a assinatura não prevê um tipo de resultado assíncrono, a chamada provavelmente ocorre de forma síncrona e o cancelamento do registro passa a ter efeito imediatamente após o retorno da função. Pergunta Q-df3005625905440a (aberta)

Tratamento de erros

A função é especificada com noexcept [SWS_ANM_01013] e, portanto, não lança exceções. Na especificação não estão previstos códigos de erro nem reações de erro separadas para o chamador.

Simultaneidade e restrições

Em relação à segurança de threads, a função é explicitamente classificada como not thread-safe [SWS_ANM_01013]. Unidades de software chamadoras devem, portanto, assegurar por meio de medidas de sincronização adequadas que o cancelamento de registro não seja executado concorrentemente a outros acessos à mesma instância.