Pular para o conteúdo principal

Operações e notificações assíncronas

Para operações que podem ser lentas ou computacionalmente caras, o SDK de Lobby e Matchmaking do PlayFab expõe APIs assíncronas. As APIs assíncronas permitem iniciar operações caras ou lentas a partir dos seus threads principais e sondar a conclusão dessas operações em um thread de sua escolha. Esse mesmo mecanismo de sondagem também é usado para entregar notificações assíncronas de atualizações do SDK ao código do seu título. Esta página apresenta uma visão geral dos padrões de API assíncrona do SDK de Lobby e Matchmaking do PlayFab e das práticas recomendadas para programar com eles.

Padrões básicos de API

Há dois tipos de padrões de API assíncrona a serem considerados no SDK de Lobby e Matchmaking do PlayFab:
  1. Operações assíncronas
  2. Notificações assíncronas

Operações assíncronas

É simples usar as APIs assíncronas do SDK. O padrão geral para iniciar e concluir operações assíncronas é o seguinte:
  1. Faça uma chamada de método normal à API assíncrona apropriada de sua escolha. As operações assíncronas comuns que você provavelmente usará incluem:
  2. Verifique o valor de retorno HRESULT da API com as macros SUCCEEDED() ou FAILED(). Esse valor retornado de forma síncrona informará se a operação foi iniciada com êxito.
O valor de retorno síncrono de uma chamada de API assíncrona NÃO informa se a operação foi concluída com êxito. Para obter mais informações sobre erros síncronos e assíncronos, confira a documentação de tratamento de erros do SDK.
  1. Sonde a conclusão da operação assíncrona procurando a “alteração de estado de conclusão” associada à operação, que será fornecida por PFMultiplayerStartProcessingLobbyStateChanges() ou PFMultiplayerStartProcessingMatchmakingStateChanges. Um exemplo da “alteração de estado de conclusão” associada a PFMultiplayerCreateAndJoinLobby() é PFLobbyCreateAndJoinLobbyCompletedStateChange. Informações mais detalhadas sobre o que são as “alterações de estado” e como elas funcionam podem ser encontradas na seção Alterações de estado.
  2. Verifique o valor result da alteração de estado de conclusão para determinar se a operação teve êxito ou falhou. Informações mais detalhadas sobre esses valores de erro podem ser encontradas na documentação de tratamento de erros do SDK.

Notificações assíncronas

Alguns recursos geram notificações assíncronas de alterações no SDK de Lobby e Matchmaking. As notificações comuns incluem:
  1. Notificações de atualização do lobby.
  2. Notificações de desconexão do lobby.
  3. Notificações de alteração de status do tíquete de matchmaking.
Essas notificações assíncronas serão fornecidas a você pelo SDK como “alterações de estado” por meio de PFMultiplayerStartProcessingLobbyStateChanges() e PFMultiplayerStartProcessingMatchmakingStateChanges. Informações mais detalhadas sobre o que são as “alterações de estado” e como elas funcionam podem ser encontradas na seção Alterações de estado.

Alterações de estado

O modelo de API assíncrona do SDK de Lobby e Matchmaking é construído em torno das structs PFLobbyStateChange e PFMatchmakingStateChange. As PFLobbyStateChanges notificam você sobre alterações no subsistema de lobby, e as PFMatchmakingStateChanges notificam você sobre alterações no subsistema de matchmaking. Essas “alterações de estado” são notificações assíncronas de eventos do SDK. Essas notificações são enfileiradas internamente, e você as processa chamando PFMultiplayerStartProcessingLobbyStateChanges() e PFMultiplayerStartProcessingMatchmakingStateChanges. Essas funções retornarão todas as alterações de estado enfileiradas (do respectivo subsistema de API) como listas que você pode percorrer e processar individualmente. Cada alteração de estado tem um campo stateChangeType correspondente que pode ser inspecionado para determinar sobre qual alteração de estado específica você está sendo notificado. Depois de saber qual alteração de estado você recebeu, poderá converter a struct genérica PFLobbyStateChange ou PFMatchmakingStateChange em um tipo mais específico de struct de alteração de estado para inspecionar os dados específicos desse evento. Normalmente, o processamento de alterações de estado é implementado como uma simples instrução switch que delega cada alteração de estado a um manipulador. Depois que a lista de alterações de estado de PFMultiplayerStartProcessingLobbyStateChanges ou PFMultiplayerStartProcessingMatchmakingStateChanges for processada, ela precisará ser devolvida a PFMultiplayerFinishProcessingMatchmakingStateChanges() ou PFMultiplayerFinishProcessingMatchmakingStateChanges(), respectivamente.

Contextos de operações assíncronas

Cada API assíncrona inclui um parâmetro void* asyncContext. Esse valor é um parâmetro de passagem que será definido na alteração de estado de conclusão associada a essa chamada de API quando ela for fornecida por PFMultiplayerStartProcessingLobbyStateChanges() ou PFMultiplayerStartProcessingMatchmakingStateChanges(). Esse valor oferece um mecanismo para anexar contextos arbitrários, do tamanho de um ponteiro, às suas chamadas de API assíncrona. Esses contextos podem ser usados em muitos cenários, incluindo:
  1. associar dados específicos do título a uma chamada do SDK
  2. vincular várias operações assíncronas com um identificador compartilhado
Esses contextos assíncronos não são obrigatórios para o uso do SDK, mas podem facilitar a escrita de parte da lógica do título.

Enfileiramento de operações

Com frequência, ao trabalhar com APIs assíncronas, várias operações assíncronas precisam ser executadas sequencialmente como parte de um fluxo assíncrono maior. No SDK de Lobby e Matchmaking, um exemplo seria criar um lobby e enviar convites aos seus amigos para esse lobby. De forma serializada, esse fluxo seria:
  1. Chamar PFMultiplayerCreateAndJoinLobby() para criar um lobby do PlayFab e ingressar nele.
  2. Aguardar a PFLobbyCreateAndJoinLobbyCompletedStateChange refletir que o lobby foi criado e ingressado com êxito.
  3. Chamar PFLobbySendInvite() para cada amigo convidado.
  4. Aguardar a PFLobbySendInviteCompletedStateChange refletir que o convite foi enviado com êxito.
Para fluxos e lógicas de título mais complicados, esse padrão serializado pode ser apropriado. No entanto, para fluxos mais simples, o SDK oferece uma alternativa que pretende simplificar o código do título: Muitas APIs assíncronas do SDK oferecem suporte ao enfileiramento de operações dependentes antes que uma operação anterior tenha sido totalmente concluída. No exemplo anterior, você pode enviar um convite para um lobby antes de ver que o lobby foi criado com êxito. Efetivamente, o enfileiramento permite agrupar uma coleção de operações assíncronas, iniciá-las todas de uma vez e consolidar o tratamento de erros em um único ponto de falha.

Controlar o trabalho assíncrono

Às vezes, é necessário que os títulos controlem onde o trabalho assíncrono é feito para evitar a contenção de CPU entre bibliotecas e as cargas de trabalho principais de CPU do título. O SDK de Lobby e Matchmaking permite controlar como o trabalho assíncrono é executado por meio do Controle da afinidade de thread

Controle da afinidade de thread

Por padrão, o trabalho assíncrono do SDK é feito em threads em segundo plano cuidadosamente controlados. Alguns títulos precisam de controle geral sobre onde esses threads em segundo plano são agendados para evitar a contenção de CPU. Para esses títulos, o SDK de Lobby e Matchmaking fornece PFMultiplayerSetThreadAffinityMask(). Nas plataformas compatíveis, isso permite limitar quais núcleos de CPU serão usados pelos threads em segundo plano do SDK. Dessa forma, você pode garantir que determinados núcleos fiquem reservados para suas próprias cargas de trabalho de CPU, sem nenhuma contenção.
Última modificação em 8 de outubro de 2026