Exemple de configuration d'un fournisseur personnalisé

Cette rubrique fournit un exemple de configuration d’un fournisseur asynchrone personnalisé. Lors de l’écriture d’un fournisseur asynchrone personnalisé, les méthodes asynchrones sont démarrées par un appel à XAsyncBegin. Cette fonction possède un paramètre de rappel qui implémente, par exemple, la gestion des changements d’état, la mise en file d’attente des rappels et le déclenchement de l’achèvement.

struct Context
{
    uint64_t result;
};

Context* context = new Context{ 0 };
// Assume that the async block is already filled out with the completion callback and task queue.
HRESULT hr = XAsyncBegin(async, context, ProviderFuncIdentity, __FUNCTION__,
    [](XAsyncOp op, const XAsyncProviderData* providerData)
    {
        Context* context =
        reinterpret_cast<Context*>(providerData->context);
        switch (op)
        {
            case XAsyncOp::Begin:
                return XAsyncSchedule(providerData->async, 0);

            case XAsyncOp::Cleanup:
                delete context;
                break;

            case XAsyncOp::GetResult:
                memcpy(providerData->buffer, &context->result, sizeof(uint64_t));
                break;

            case XAsyncOp::DoWork:
                context->result = 12345678;
                XAsyncComplete(providerData->async, S_OK, sizeof(uint64_t));
                break;

            case XAsyncOp::Cancel:
                // This call can't be canceled.
                break;
        }

    return S_OK;
});

Il y a beaucoup d’éléments à analyser ici, mais l’idée de base est simple : appelez XAsyncBegin et transmettez-lui un rappel de fournisseur pour gérer les différents changements d’état. Rappelez-vous que le bloc asynchrone contient la file d’attente de tâches à utiliser et une implémentation facultative d’un rappel d’achèvement. Le rappel doit ensuite gérer les cinq cas différents de l’exécution de la tâche asynchrone, comme indiqué dans le tableau suivant.

Cas du fournisseur	Responsabilité
`Begin`	Appelé immédiatement par l’appel à `XAsyncBegin`. Ce cas est chargé de planifier le rappel de travail asynchrone dans la file d’attente de tâches. Cette opération est gérée par un appel à XAsyncSchedule. Celui-ci met ce rappel en file d’attente pour qu’il s’exécute à nouveau avec le cas `DoWork` via le port de travail de la file d’attente de tâches.
`Cleanup`	Appelé lorsque la tâche asynchrone se termine et que toutes les données internes créées pour le suivi peuvent être supprimées. Dans l’exemple de code précédent, ce cas nettoie la structure `Context`, qui avait été allouée pour suivre les données de résultat.
`GetResult`	Appelé lorsque l’utilisateur appelle XAsyncGetResult. Le cas doit alors écrire dans la mémoire tampon de sortie qui lui est transmise. Le résultat asynchrone d’origine doit donc avoir été enregistré quelque part. L’exemple de code précédent l’enregistre dans la structure `Context`. Les fonctions d’API asynchrones du Microsoft Game Development Kit (GDK) qui renvoient des données d’une tâche asynchrone appellent `XAsyncGetResult` en interne et convertissent ces données sous la forme adaptée à l’appelant. Nous recommandons cette approche pour travailler avec les résultats.
`DoWork`	Appelé via la file d’attente de tâches dont le port de travail est distribué. Cela signifie que le frame de pile de ce rappel s’exécute sur le thread prévu, en fonction de la configuration de la file d’attente de tâches. Tout le travail doit être effectué ici. Dans l’implémentation du fournisseur asynchrone interne de XAsyncRun, c’est ici que le rappel de travail transmis est exécuté. Pour les fournisseurs personnalisés, le travail peut être effectué directement dans le rappel ou à l’aide d’une méthode personnalisée qui encapsule la fonctionnalité. Une fois le travail terminé, XAsyncComplete doit être appelé. Cette fonction effectue deux tâches. Premièrement, elle indique si des données de sortie sont nécessaires en fournissant une taille de données. Si une valeur supérieure à zéro est fournie, une mémoire tampon interne est allouée pour que le cas `GetResult` puisse y écrire. Deuxièmement, elle met en file d’attente un appel au rappel d’achèvement pour qu’il s’exécute sur le port d’achèvement de la file d’attente de tâches. Le code d’état d’achèvement transmis à `XAsyncComplete` devient le code renvoyé par un appel à XAsyncGetStatus.
`Cancel`	Déclenché par un appel externe à XAsyncCancel. Si ce cas n’est pas implémenté, rien ne se passe. Pour permettre l’annulation, le fournisseur doit pouvoir signaler à tout travail en cours d’exécution de s’arrêter. Le cas `DoWork` doit alors appeler `XAsyncComplete` avec l’état `E_ABORT`.

Documentation de référence de l’API

XAsyncProvider (contenu de l’API)
- Fonctions
xasync (contenu de l’API)
- Fonctions

Voir aussi

Vue d’ensemble de la bibliothèque XAsyncProvider Configurer des méthodes d’appel (exemple) Configurer des données de retour (exemple) Configurer la possibilité d’annulation (exemple) XAsyncProvider

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Build and Develop

Documentation de référence de l’API

Voir aussi

​Documentation de référence de l’API

​Voir aussi

Documentation de référence de l’API

Voir aussi