Modelo de programação assíncrona

​

Modelo conceitual

​

Requisitos

1. Preferir chamadas síncronas a chamadas assíncronas
2. Fornecer modo assíncrono com sondagem
3. Fornecer modo assíncrono com retornos de chamada
4. Fornecer controle sobre em qual thread o trabalho assíncrono é executado
5. Fornecer controle sobre em qual thread os retornos de chamada de conclusão são executados

​

Tipos de APIs

• Seguras para tempo crítico: Uma API segura para tempo crítico é aquela que pode ser chamada em um thread sensível ao tempo. Observe que, embora isso geralmente signifique que a API é trivial ou muito rápida, o conceito-chave é que as características de desempenho da API são consistentes. Elas são sempre síncronas e nunca precisam ter uma versão assíncrona. Essas APIs devem ser documentadas como seguras para tempo crítico.
• Não seguras para tempo crítico: Não é seguro chamar essas APIs a partir do thread de renderização. Suas características de desempenho podem variar amplamente. A maioria das APIs se enquadra nessa categoria.
• Assíncronas: Essas APIs são assíncronas por natureza, como uma chamada de serviço web. Elas usam o padrão assíncrono descrito neste tópico. As APIs assíncronas não são tão comuns no Microsoft Game Development Kit (GDK) quanto no modelo de programação ERA do XBOX One: uma API assíncrona geralmente é de longa duração e cancelável. Exceto em alguns casos de uso específicos, as APIs assíncronas terão uma versão síncrona não segura para tempo crítico. Chamar uma API assíncrona deve sempre ser seguro para tempo crítico.
• Notificações: As notificações são periódicas por natureza e não têm um fim definido. Elas estão relacionadas às APIs assíncronas, mas, devido à sua natureza periódica, devem ter aparência e comportamento diferentes para os desenvolvedores. O registro para uma notificação deve sempre ser seguro para tempo crítico.

​

Padrão de API assíncrona

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);

​

Uso da API assíncrona

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);

​

Controlando o despacho de trabalho

• Pool de threads: Os retornos de chamada enfileirados em uma fila de pool de threads são executados no pool de threads do sistema. O pool de threads invoca as chamadas em paralelo, retirando uma chamada da fila para executar, uma de cada vez, à medida que os threads do pool ficam disponíveis.
• Pool de threads serializado: Os retornos de chamada são enfileirados e executados no pool de threads, mas um de cada vez.
• Manual: Os retornos de chamada enfileirados em uma fila manual não são despachados automaticamente. Cabe ao desenvolvedor despachá-los em qualquer thread que desejar.
• Imediato: O modo de despacho imediato não usa fila. Ele executa imediatamente a chamada no thread que enviou o retorno de chamada.

​

Notificações

1. Modo assíncrono com sondagem
2. Modo assíncrono com retornos de chamada
3. Controle sobre em qual thread os retornos de chamada ocorrem

• Um método Register que recebe quaisquer parâmetros específicos da chamada, uma fila de tarefas, um contexto void opcional e um ponteiro de retorno de chamada fortemente tipado. O último parâmetro é um parâmetro out que retorna um token.
• Um método Unregister que recebe qualquer contexto específico da chamada e o token.
• A sondagem é suportada pela adição de um método separado que não está relacionado ao retorno de chamada de notificação.

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);

​

Biblioteca assíncrona

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. Chame XAsyncBegin com o bloco assíncrono passado pelo chamador e forneça um retorno de chamada que forneça a implementação.
2. Execute o trabalho assíncrono da chamada. Se você precisar executar o trabalho em um thread de trabalho, chame XAsyncSchedule. Se você puder realizar o trabalho usando primitivos assíncronos do sistema operacional e configurar esses primitivos rápido o suficiente para continuar seguro para tempo crítico, essa é a opção preferencial.
3. Se você precisar invocar outro trabalho assíncrono a partir de um retorno de chamada de thread de trabalho, poderá retornar E_PENDING do worker. Você também pode chamar XAsyncSchedule de dentro de um worker para reagendar trabalho adicional.
4. Quando todo o trabalho estiver concluído, chame XAsyncComplete.
5. Forneça um wrapper fortemente tipado em torno de XAsyncGetResult para retornar os resultados.
6. Se a sua chamada assíncrona não tiver carga de dados, você deverá fornecer um wrapper fortemente tipado em torno de XAsyncGetStatus e passar zero como o tamanho de buffer necessário para XAsyncComplete.

• Begin Um provedor assíncrono é invocado com esse opcode durante XAsyncBegin. Se o provedor implementar esse opcode, ele deverá iniciar sua tarefa assíncrona chamando XAsyncSchedule ou por meios externos. Esse retorno de chamada é chamado de forma síncrona na cadeia de chamadas de XAsyncBegin, portanto, nunca deve bloquear.
• DoWork Chamado nos casos em que XAsyncSchedule foi chamado para agendar trabalho assíncrono usando a fila de tarefas. A função do provedor faz todo o trabalho necessário. Ao concluir, ela chama XAsyncComplete com o código de resultado e o tamanho da carga de dados, que pode ser zero se não houver carga de dados da chamada. Se for necessário realizar mais trabalho assíncrono, o provedor poderá agendar esse trabalho e deverá retornar E_PENDING.
• GetResult Chamado para buscar o resultado da chamada. Como o tamanho dos dados é passado para XAsyncComplete durante a conclusão da chamada, nenhuma verificação de argumentos é necessária aqui: todos os buffers e tamanhos de buffer foram verificados pela biblioteca.
• Cancel Chamado quando o usuário cancela uma chamada assíncrona. Se a chamada puder ser cancelada, cancele-a e chame XAsyncComplete com E_ABORT como código de resultado.
• Cleanup Chamado quando a chamada foi totalmente concluída e o provedor pode excluir qualquer memória dinâmica.

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);
}

​

Documentação de referência da API

• XAsync (conteúdo da API)
  • Funções
    • XAsyncGetStatus
    • XAsyncGetResultSize
    • XAsyncCancel
    • XAsyncCompletionRoutine
    • XAsyncRun
  • Estruturas
    • XAsyncBlock
• XAsyncProvider (conteúdo da API)
  • Funções
    • XAsyncGetResult
    • XAsyncBegin
    • XAsyncSchedule
    • XAsyncComplete
• XTaskQueue (conteúdo da API)
  • Funções
    • xtaskqueuecreate
    • xtaskqueuedispatch
• xgamesave (conteúdo da API)
  • Funções
    • XGameSaveGetRemainingQuotaAsync
    • XGameSaveGetRemainingQuotaResult

​

Consulte também