Modèle de programmation asynchrone

​

Modèle conceptuel

​

Exigences

1. Privilégier les appels synchrones plutôt que les appels asynchrones
2. Offrir l’asynchronisme avec interrogation
3. Offrir l’asynchronisme avec rappels
4. Offrir le contrôle du thread sur lequel le travail asynchrone s’exécute
5. Offrir le contrôle du thread sur lequel les rappels d’achèvement s’exécutent

​

Types d’API

• Sécuritaire en contexte critique : Une API sécuritaire en contexte critique est une API qui peut être appelée sur un thread critique en matière de temps. Notez que, même si cela signifie généralement que l’API est triviale ou très rapide, le concept clé est que les caractéristiques de performance 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 étant sécuritaires en contexte critique.
• Non sécuritaire en contexte critique : Ces API ne peuvent pas être appelées en toute sécurité à partir du thread de rendu. Leurs caractéristiques de performance peuvent varier considérablement. La plupart des API entrent dans cette catégorie.
• Asynchrone : 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. Sauf dans quelques cas d’utilisation précis, les API asynchrones disposent d’une version synchrone non sécuritaire en contexte critique. L’appel d’une API asynchrone doit toujours être sécuritaire en contexte critique.
• Notifications : Les notifications sont de nature périodique 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 avoir une apparence et un comportement différents pour les développeurs. L’inscription à une notification doit toujours être sécuritaire en contexte critique.

​

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 des API asynchrones

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 dans une file d’attente de pool de threads sont exécutés sur le pool de threads du 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 à la fois.
• Manuel : Les rappels mis dans une file d’attente 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 n’effectue aucune mise en file d’attente. Il exécute immédiatement l’appel sur le thread qui a soumis le rappel.

​

Notifications

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

• Une méthode Register qui prend tous 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 tout contexte propre à l’appel et le jeton.
• L’interrogation est prise en charge par l’ajout d’une méthode distincte qui n’est pas liée au 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 passé 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 en utilisant des primitives asynchrones du système d’exploitation et configurer ces primitives assez rapidement pour demeurer sécuritaire en contexte critique, cette approche est à privilégier.
3. Si vous devez appeler un autre travail asynchrone à partir d’un rappel de thread de travail, vous pouvez retourner E_PENDING à partir du thread de travail. Vous pouvez également appeler XAsyncSchedule à partir d’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 aucune charge utile de données, vous devez fournir un wrapper fortement typé autour de XAsyncGetStatus et passer 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 façon synchrone dans la chaîne d’appels de XAsyncBegin; il ne doit donc jamais bloquer.
• DoWork Appelé dans les cas où XAsyncSchedule a été appelée pour planifier un travail asynchrone au moyen 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 n’a aucune charge utile de données. Si d’autres travaux asynchrones doivent être effectués, 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 passée à 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 complètement 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