Modèle de programmation asynchrone

​

Modèle conceptuel

​

Exigences

1. Préférer les appels synchrones aux appels asynchrones
2. Fournir un mode asynchrone avec interrogation
3. Fournir un mode asynchrone avec rappels
4. Permettre de contrôler le thread sur lequel s’exécute le travail asynchrone
5. Permettre de contrôler le thread sur lequel s’exécutent les rappels d’achèvement

​

Types d’API

• Sûres pour les opérations critiques en temps : une API sûre pour les opérations critiques en temps peut être appelée sur un thread critique en temps. Notez que, bien que cela signifie généralement que l’API est triviale ou très rapide, le concept clé est que les caractéristiques de performances de l’API sont constantes. Ces API sont toujours synchrones et n’ont jamais besoin d’une version asynchrone. Ces API doivent être documentées comme sûres pour les opérations critiques en temps.
• Non sûres pour les opérations critiques en temps : ces API ne peuvent pas être appelées en toute sécurité depuis le thread de rendu. Leurs caractéristiques de performances peuvent varier considérablement. La plupart des API entrent dans cette catégorie.
• Asynchrones : ces API sont asynchrones par nature, comme un appel de service web. Elles utilisent le modèle asynchrone décrit dans cette rubrique. Les API asynchrones sont moins courantes dans le Microsoft Game Development Kit (GDK) que dans le modèle de programmation ERA de la XBOX One : une API asynchrone est généralement de longue durée et annulable. À l’exception de quelques cas d’usage spécifiques, les API asynchrones disposent d’une version synchrone non sûre pour les opérations critiques en temps. L’appel d’une API asynchrone doit toujours être sûr pour les opérations critiques en temps.
• Notifications : les notifications sont périodiques par nature et n’ont pas de fin définie. Elles sont liées aux API asynchrones, mais en raison de leur nature périodique, elles doivent se présenter et se comporter différemment pour les développeurs. L’inscription à une notification doit toujours être sûre pour les opérations critiques en temps.

​

Modèle d’API asynchrone

typedef void CALLBACK XAsyncCompletionRoutine(struct XAsyncBlock* asyncBlock);

struct XAsyncBlock
{
    XTaskQueueHandle queue;
    void* context;
    XAsyncCompletionRoutine* callback;
    unsigned char internal[sizeof(void*) * 4];
};

STDAPI XAsyncGetStatus(XAsyncBlock* asyncBlock, bool wait);

STDAPI XAsyncGetResultSize(XAsyncBlock* asyncBlock, size_t* bufferSize);

STDAPI_(void) XAsyncCancel(XAsyncBlock* asyncBlock);

typedef HRESULT CALLBACK XAsyncWork(XAsyncBlock* asyncBlock);

STDAPI XAsyncRun(XAsyncBlock* asyncBlock, XAsyncWork* work);

​

Utilisation de l’API asynchrone

HRESULT XGameSaveGetRemainingQuota(XGameSaveProviderHandle provider,
int64_t* remainingQuota);

HRESULT XGameSaveGetRemainingQuotaAsync(XGameSaveProviderHandle
provider, XAsyncBlock* async);

HRESULT XGameSaveGetRemainingQuotaResult(XAsyncBlock* async,
int64_t* remainingQuota);

// providerHandle is a previously obtained XGameSaveProviderHandle.

XAsyncBlock* b = new XAsyncBlock;
ZeroMemory(b, sizeof(XAsyncBlock));
b->context = this;
b->queue = queue;
b->callback = [](XAsyncBlock* async)
{
    int64_t remainingQuota;
    if(SUCCEEDED(XGameSaveGetRemainingQuotaResult(async, &remainingQuota)))
    {
        printf("Remaining quota: %irn", remainingQuota);
    }
    delete async;
};
XGameSaveGetRemainingQuotaAsync(providerHandle, b);

HRESULT QueryUpdateStatusAsyncResult(_Inout_ XAsyncBlock* block);

​

Contrôle de la distribution du travail

• Pool de threads : les rappels mis en file d’attente dans une file de pool de threads sont exécutés sur le pool de threads système. Le pool de threads appelle les rappels en parallèle, en prenant tour à tour un appel à exécuter dans la file d’attente à mesure que des threads du pool deviennent disponibles.
• Pool de threads sérialisé : les rappels sont mis en file d’attente et exécutés sur le pool de threads, mais un seul à la fois.
• Manuel : les rappels mis en file d’attente dans une file manuelle ne sont pas automatiquement distribués. Il revient au développeur de les distribuer sur le thread de son choix.
• Immédiat : le mode de distribution immédiat ne met rien en file d’attente. Il exécute immédiatement l’appel sur le thread qui a soumis le rappel.

​

Notifications

1. Mode asynchrone avec interrogation
2. Mode asynchrone avec rappels
3. Contrôle du thread sur lequel les rappels se produisent

• Une méthode Register qui prend les paramètres propres à l’appel, une file d’attente de tâches, un contexte void facultatif et un pointeur de rappel fortement typé. Le dernier paramètre est un paramètre out qui retourne un jeton.
• Une méthode Unregister qui prend le contexte propre à l’appel et le jeton.
• L’interrogation est prise en charge en ajoutant une méthode distincte, sans lien avec le rappel de notification.

struct XTaskQueueRegistrationToken;

typedef void MessageAvailableCallback(void* context, const MSG* msg);

HRESULT RegisterMessageAvailable(
    XTaskQueueHandle queue,
    void* context,
    MessageAvailableCallback* callback,
    XTaskQueueRegistrationToken * token);

bool UnregisterMessageAvailable(XTaskQueueRegistrationToken token, bool
wait);

// Usage.
XTaskQueueRegistrationToken token;
RegisterMessageAvailable(queue, nullptr, [](void*, const MSG* msg)
{
    printf("Message: %drn", msg->message);
}, &token);

​

Bibliothèque asynchrone

enum class XAsyncOp : uint32_t
{
    Begin,
    DoWork,
    GetResult,
    Cancel,
    Cleanup
};

struct XAsyncProviderData
{
    XAsyncBlock* async;  
    size_t bufferSize;  
    void* buffer;  
    void* context;
};

typedef HRESULT CALLBACK XAsyncProvider(
_In_ XAsyncOp op,
_Inout_ XAsyncProviderData* data);

STDAPI XAsyncBegin (
_Inout_ XAsyncBlock* asyncBlock,
_In_opt_ void* context,
_In_opt_ void* identity,
_In_opt_ const char* identityName,
_In_ XAsyncProvider* provider);

STDAPI XAsyncSchedule(
_Inout_ XAsyncBlock* asyncBlock,
_In_ uint32_t delayInMs);

STDAPI_(void) XAsyncComplete(
_Inout_ XAsyncBlock* asyncBlock,
_In_ HRESULT result,
_In_ size_t requiredBufferSize);

STDAPI XAsyncGetResult(
_Inout_ XAsyncBlock* asyncBlock,
_In_opt_ void* identity,
_In_ size_t bufferSize,
_Out_writes_bytes_opt_(bufferSize) void* buffer,
_Out_opt_ size_t* bufferUsed);

1. Appelez XAsyncBegin avec le bloc asynchrone transmis par l’appelant, et fournissez un rappel qui fournit l’implémentation.
2. Effectuez le travail asynchrone de l’appel. Si vous devez exécuter le travail sur un thread de travail, appelez XAsyncSchedule. Si vous pouvez effectuer le travail à l’aide de primitives asynchrones du système d’exploitation et configurer ces primitives suffisamment rapidement pour rester sûr pour les opérations critiques en temps, c’est préférable.
3. Si vous devez appeler un autre travail asynchrone à partir d’un rappel de thread de travail, vous pouvez retourner E_PENDING depuis le thread de travail. Vous pouvez également appeler XAsyncSchedule depuis un thread de travail pour replanifier du travail supplémentaire.
4. Lorsque tout le travail est terminé, appelez XAsyncComplete.
5. Fournissez un wrapper fortement typé autour de XAsyncGetResult pour retourner les résultats.
6. Si votre appel asynchrone n’a pas de charge utile de données, vous devez fournir un wrapper fortement typé autour de XAsyncGetStatus et transmettre zéro comme taille de mémoire tampon requise à XAsyncComplete.

• Begin Un fournisseur asynchrone est appelé avec ce code d’opération pendant XAsyncBegin. Si le fournisseur implémente ce code d’opération, il doit démarrer sa tâche asynchrone en appelant XAsyncSchedule ou par des moyens externes. Ce rappel est appelé de manière synchrone dans la chaîne d’appels de XAsyncBegin ; il ne doit donc jamais être bloquant.
• DoWork Appelé lorsque XAsyncSchedule a été appelé pour planifier un travail asynchrone à l’aide de la file d’attente de tâches. La fonction du fournisseur effectue tout le travail nécessaire. Une fois terminé, elle appelle XAsyncComplete avec le code de résultat et la taille de la charge utile de données, qui peut être zéro si l’appel ne produit aucune charge utile de données. Si du travail asynchrone supplémentaire doit être effectué, le fournisseur peut planifier ce travail et doit retourner E_PENDING.
• GetResult Appelé pour récupérer le résultat de l’appel. Comme la taille des données est transmise à XAsyncComplete lors de l’achèvement de l’appel, aucune vérification des arguments n’est nécessaire ici : toutes les mémoires tampons et leurs tailles ont été vérifiées par la bibliothèque.
• Cancel Appelé lorsque l’utilisateur annule un appel asynchrone. Si l’appel peut être annulé, annulez-le et appelez XAsyncComplete avec E_ABORT comme code de résultat.
• Cleanup Appelé lorsque l’appel est entièrement terminé et que le fournisseur peut supprimer toute mémoire dynamique.

UINT64 Factorial(UINT64 value)
{
    UINT64 result = 1;

    while (value != 0)
    {       
        result *= value;
        value--;
    }

    return result;
}

HRESULT FactorialAsync(UINT64 value, XAsyncBlock* async)
{
    struct CallData
    {
        UINT64 value;
        UINT64 result;
    };

    CallData* data = new CallData();
    data->value = value;
    data->result = 1;

    HRESULT hr = XAsyncBegin (async, data, FactorialAsync, __FUNCTION__, []
        (XAsyncOp op, XAsyncProviderData* data)
    {
        CallData* d = (CallData*)data->context;

        switch (op)
        {
        case XAsyncOp::Begin:
            return XAsyncSchedule(data->async, 0);

        case XAsyncOp::Cleanup:
            delete d;
            break;

        case XAsyncOp::GetResult:
            CopyMemory(data->buffer, &d->result, sizeof(UINT64));
            break;
 
        case XAsyncOp::DoWork:
            data->result = Factorial(data.Value);
            XAsyncComplete(data->async, S_OK, sizeof(UINT64));
            break;
        }

        return S_OK;
    });

    return hr;
}

HRESULT FactorialAsyncResult(XAsyncBlock* async, UINT64* result)
{
    return XAsyncGetResult(async, FactorialAsync, sizeof(UINT64), result);
}

​

Documentation de référence de l’API

• XAsync (contenu de l’API)
  • Fonctions
    • XAsyncGetStatus
    • XAsyncGetResultSize
    • XAsyncCancel
    • XAsyncCompletionRoutine
    • XAsyncRun
  • Structures
    • XAsyncBlock
• XAsyncProvider (contenu de l’API)
  • Fonctions
    • XAsyncGetResult
    • XAsyncBegin
    • XAsyncSchedule
    • XAsyncComplete
• XTaskQueue (contenu de l’API)
  • Fonctions
    • xtaskqueuecreate
    • xtaskqueuedispatch
• xgamesave (contenu de l’API)
  • Fonctions
    • XGameSaveGetRemainingQuotaAsync
    • XGameSaveGetRemainingQuotaResult

​

Voir aussi