Opérations et notifications asynchrones

Pour les opérations susceptibles d’être lentes ou coûteuses en calcul, le SDK PlayFab Lobby et Matchmaking expose des API asynchrones. Les API asynchrones vous permettent de démarrer des opérations coûteuses ou lentes depuis vos threads principaux et d’interroger l’achèvement de ces opérations sur le thread de votre choix. Ce même mécanisme d’interrogation sert également à transmettre à votre code de titre des notifications asynchrones de mises à jour du SDK. Cette page présente les modèles d’API asynchrones du SDK PlayFab Lobby et Matchmaking ainsi que les bonnes pratiques de programmation associées.

Modèles d’API de base

Il existe deux types de modèles d’API asynchrones à connaître dans le SDK PlayFab Lobby et Matchmaking :

Opérations asynchrones
Notifications asynchrones

Opérations asynchrones

Les API asynchrones du SDK sont simples à utiliser. Le modèle général de démarrage et d’achèvement des opérations asynchrones est le suivant :

Effectuez un appel de méthode normal à l’API asynchrone appropriée de votre choix. Parmi les opérations asynchrones courantes que vous utiliserez probablement, citons :
Vérifiez la valeur de retour HRESULT de l’API à l’aide des macros SUCCEEDED() ou FAILED(). Cette valeur renvoyée de manière synchrone vous indique si l’opération a bien démarré.

La valeur de retour synchrone d’un appel d’API asynchrone ne vous indique PAS si l’opération s’est terminée avec succès. Pour plus d’informations sur les erreurs synchrones et asynchrones, consultez la documentation sur la gestion des erreurs du SDK.

Interrogez l’achèvement de l’opération asynchrone en attendant que le « changement d’état d’achèvement » de l’opération associée soit fourni par PFMultiplayerStartProcessingLobbyStateChanges() or PFMultiplayerStartProcessingMatchmakingStateChanges. Un exemple de « changement d’état d’achèvement » associé à PFMultiplayerCreateAndJoinLobby() est PFLobbyCreateAndJoinLobbyCompletedStateChange. Des informations plus détaillées sur ce que sont les « changements d’état » et sur leur fonctionnement sont disponibles dans la section Changements d’état.
Vérifiez la valeur result du changement d’état d’achèvement pour déterminer si l’opération a réussi ou échoué. Des informations plus détaillées sur ces valeurs d’erreur sont disponibles dans la documentation sur la gestion des erreurs du SDK.

Notifications asynchrones

Certaines fonctionnalités génèrent des notifications asynchrones de modifications dans le SDK Lobby et Matchmaking. Les notifications courantes sont notamment :

Ces notifications asynchrones vous sont fournies par le SDK sous forme de « changements d’état » via PFMultiplayerStartProcessingLobbyStateChanges() and PFMultiplayerStartProcessingMatchmakingStateChanges. Des informations plus détaillées sur ce que sont les « changements d’état » et sur leur fonctionnement sont disponibles dans la section Changements d’état.

Changements d’état

Le modèle d’API asynchrone du SDK Lobby et Matchmaking repose sur les structs PFLobbyStateChange and PFMatchmakingStateChange . Les PFLobbyStateChanges vous informent des modifications du sous-système de lobby et les PFMatchmakingStateChanges vous informent des modifications du sous-système de matchmaking. Ces « changements d’état » sont des notifications asynchrones d’événements provenant du SDK. Ces notifications sont mises en file d’attente en interne, et vous les traitez en appelant PFMultiplayerStartProcessingLobbyStateChanges() and PFMultiplayerStartProcessingMatchmakingStateChanges. Ces fonctions renvoient tous les changements d’état en file d’attente (pour leur sous-système d’API respectif) sous forme de listes que vous pouvez parcourir et traiter individuellement. Chaque changement d’état possède un champ stateChangeType correspondant, que vous pouvez examiner pour déterminer le changement d’état spécifique dont vous êtes informé. Une fois que vous savez quel changement d’état vous a été fourni, vous pouvez convertir le struct générique PFLobbyStateChange ou PFMatchmakingStateChange en un type de struct de changement d’état plus spécifique afin d’examiner les données propres à cet événement. En général, le traitement des changements d’état est implémenté sous la forme d’une simple instruction switch qui délègue chaque changement d’état à un gestionnaire. Une fois traitée, la liste des changements d’état obtenue de PFMultiplayerStartProcessingLobbyStateChanges ou de PFMultiplayerStartProcessingMatchmakingStateChanges doit être renvoyée à PFMultiplayerFinishProcessingMatchmakingStateChanges() or PFMultiplayerFinishProcessingMatchmakingStateChanges(), respectivement.

//
// Process Lobby state changes
//
uint32_t lobbyStateChangeCount;
const PFLobbyStateChange * const * lobbyStateChanges;
HRESULT hr = PFMultiplayerStartProcessingLobbyStateChanges(m_pfmHandle, &lobbyStateChangeCount, &lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < lobbyStateChangeCount; ++i)
{
    const PFLobbyStateChange* stateChange = lobbyStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFLobbyStateChangeType::CreateAndJoinLobbyCompleted:
        {
            HandleCreateAndJoinLobbyCompleted(
                static_cast<const PFLobbyCreateAndJoinLobbyCompletedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingLobbyStateChanges(m_pfmHandle, lobbyStateChangeCount, lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

//
// Process Match state changes
//
uint32_t matchStateChangeCount;
const PFMatchmakingStateChange * const * matchStateChanges;
hr = PFMultiplayerStartProcessingMatchmakingStateChanges(m_pfmHandle, &matchStateChangeCount, &matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < matchStateChangeCount; ++i)
{
    const PFMatchmakingStateChange* stateChange = matchStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFMatchmakingStateChangeType::TicketStatusChanged:
        {
            HandleMatchmakingTicketStatusChanged(
                static_cast<const PFMatchmakingTicketStatusChangedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(m_pfmHandle, matchStateChangeCount, matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

Contextes des opérations asynchrones

Chaque API asynchrone comprend un paramètre void* asyncContext. Cette valeur est un paramètre transmis tel quel, qui sera défini dans le changement d’état d’achèvement associé à cet appel d’API lorsqu’il sera fourni par PFMultiplayerStartProcessingLobbyStateChanges() ou PFMultiplayerStartProcessingMatchmakingStateChanges(). Cette valeur vous offre un mécanisme permettant d’attacher des contextes arbitraires de la taille d’un pointeur à vos appels d’API asynchrones. Ces contextes peuvent être utilisés dans de nombreux scénarios, notamment :

associer des données propres au titre à un appel du SDK
relier plusieurs opérations asynchrones à l’aide d’un identifiant partagé

Ces contextes asynchrones ne sont pas obligatoires pour utiliser le SDK, mais ils peuvent faciliter l’écriture de certaines logiques de titre.

Mise en file d’attente des opérations

Souvent, lors de l’utilisation d’API asynchrones, plusieurs opérations asynchrones doivent s’exécuter séquentiellement dans le cadre d’un flux asynchrone plus large. Dans le SDK Lobby et Matchmaking, un exemple serait la création d’un lobby et l’envoi d’invitations à vos amis pour ce lobby. De manière séquentielle, ce flux se présenterait ainsi :

Appeler PFMultiplayerCreateAndJoinLobby() pour créer et rejoindre un lobby PlayFab.
Attendre que PFLobbyCreateAndJoinLobbyCompletedStateChange indique que le lobby a bien été créé et rejoint.
Appeler PFLobbySendInvite() pour chaque ami invité.
Attendre que PFLobbySendInviteCompletedStateChange indique que l’invitation a bien été envoyée.

Pour des flux et une logique de titre plus complexes, ce modèle séquentiel peut être approprié. Toutefois, pour des flux plus simples, le SDK propose une alternative destinée à simplifier le code du titre : De nombreuses API asynchrones du SDK prennent en charge la mise en file d’attente d’opérations dépendantes avant qu’une opération précédente ne soit entièrement terminée. Dans l’exemple précédent, vous pouvez envoyer une invitation pour un lobby avant d’avoir constaté que le lobby a bien été créé. En pratique, la mise en file d’attente vous permet de regrouper un ensemble d’opérations asynchrones, de les lancer toutes en même temps et de centraliser la gestion des erreurs en un seul point d’échec.

PFLobbyHandle newLobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobby(m_pfmHandle, myPlayerEntityId, newLobbyConfiguration, nullptr, nullptr, &newLobby);
if (SUCCEEDED(hr))
{
    for (size_t i = 0; SUCCEEDED(hr) && i < friends.size(); ++i)
    {
        hr = PFLobbySendInvite(m_pfmHandle, myPlayerEntityId, friends[i], nullptr);
    }

    if (SUCCEEDED(hr))
    {
        m_lobby = newLobby;
        Log("Created lobby and invited %zu friends!", friends.size());
    }
    else
    {
        // For the purposes of demonstration, we could have a policy that we shouldn't bother with any lobbies where
        // we couldn't invite all of our friends.
        (void) PFLobbyLeave(newLobby, myPlayerEntityId, nullptr);
    }
}

Contrôle du travail asynchrone

Il est parfois nécessaire que les titres contrôlent l’endroit où le travail asynchrone est effectué, afin d’éviter la contention du processeur entre les bibliothèques et les charges de travail processeur principales du titre. Le SDK Lobby et Matchmaking vous permet de contrôler l’exécution du travail asynchrone via le Contrôle de l’affinité des threads

Contrôle de l’affinité des threads

Par défaut, le travail asynchrone du SDK est effectué sur des threads d’arrière-plan soigneusement contrôlés. Certains titres ont besoin d’un contrôle grossier sur l’emplacement où ces threads d’arrière-plan sont planifiés, afin d’éviter la contention du processeur. Pour ces titres, le SDK Lobby et Matchmaking fournit PFMultiplayerSetThreadAffinityMask(). Sur les plateformes prises en charge, cela vous permet de limiter les cœurs de processeur utilisés pour les threads d’arrière-plan du SDK. Vous pouvez ainsi garantir que certains cœurs sont réservés à vos propres charges de travail processeur, sans aucune contention.

XBOX Services

PlayFab

Guide des opérations asynchrones du SDK C++ Lobby et Matchmaking

Opérations et notifications asynchrones

Modèles d’API de base

Opérations asynchrones

Notifications asynchrones

Changements d’état

Contextes des opérations asynchrones

Mise en file d’attente des opérations

Contrôle du travail asynchrone

Contrôle de l’affinité des threads

​Opérations et notifications asynchrones

​Modèles d’API de base

​Opérations asynchrones

​Notifications asynchrones

​Changements d’état

​Contextes des opérations asynchrones

​Mise en file d’attente des opérations

​Contrôle du travail asynchrone

​Contrôle de l’affinité des threads

Opérations et notifications asynchrones

Modèles d’API de base

Opérations asynchrones

Notifications asynchrones

Changements d’état

Contextes des opérations asynchrones

Mise en file d’attente des opérations

Contrôle du travail asynchrone

Contrôle de l’affinité des threads