Fazendo chamadas assíncronas no SDK unificado do PlayFab

Uma API assíncrona é uma API que retorna rapidamente, mas inicia uma tarefa assíncrona, e o resultado é retornado depois que a tarefa é concluída. Tradicionalmente, os jogos têm pouco controle sobre qual thread executa a tarefa assíncrona e qual thread retorna os resultados ao usar um callback de conclusão. Alguns jogos são projetados para que uma seção do heap seja acessada por apenas uma thread, a fim de evitar qualquer necessidade de sincronização de threads. Se o callback de conclusão não for chamado a partir de uma thread controlada pelo jogo, atualizar o estado compartilhado com o resultado de uma tarefa assíncrona exigirá sincronização de threads. O SDK unificado do PlayFab expõe uma API C assíncrona que dá aos desenvolvedores controle direto das threads ao fazer uma chamada à API assíncrona. Aqui está um exemplo básico que chama PFProfilesGetProfileAsync:

    XAsyncBlock* asyncBlock = new XAsyncBlock();
    asyncBlock->queue = GlobalState()->queue;
    asyncBlock->context = nullptr;
    asyncBlock->callback = [](XAsyncBlock* asyncBlock)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // take ownership of XAsyncBlock
        
        size_t bufferSize;
        HRESULT hr = PFProfilesGetProfileGetResultSize(asyncBlock, &bufferSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getProfileResultBuffer(bufferSize);
            PFProfilesGetEntityProfileResponse* getProfileResponseResult{ nullptr };
            PFProfilesGetProfileGetResult(asyncBlock, getProfileResultBuffer.size(), getProfileResultBuffer.data(), &getProfileResponseResult, nullptr);
        }
    };

    PFProfilesGetEntityProfileRequest profileRequest{};
    HRESULT hr = PFProfilesGetProfileAsync(GlobalState()->entityHandle, &profileRequest, asyncBlock);

Para entender esse padrão de chamada, você precisa entender como usar o XAsyncBlock e o XTaskQueueHandle. O XAsyncBlock carrega todas as informações relacionadas à tarefa assíncrona e ao callback de conclusão. O XTaskQueueHandle permite determinar qual thread executa a tarefa assíncrona e qual thread chama o callback de conclusão do XAsyncBlock.

O XAsyncBlock

Vamos examinar o XAsyncBlock em detalhes. Ele é uma struct definida da seguinte forma:

typedef struct XAsyncBlock
{
    /// <summary>
    /// The queue to queue the call on
    /// </summary>
    XTaskQueueHandle queue;

    /// <summary>
    /// Optional context pointer to pass to the callback
    /// </summary>
    void* context;

    /// <summary>
    /// Optional callback that will be invoked when the call completes
    /// </summary>
    XAsyncCompletionRoutine* callback;

    /// <summary>
    /// Internal use only
    /// </summary>
    unsigned char internal[sizeof(void*) * 4];
};

O XAsyncBlock contém:

queue - um XTaskQueueHandle, que é um identificador que representa informações sobre onde executar uma parte do trabalho. Se esse parâmetro não for definido, uma fila padrão será usada.
context - permite passar dados para a função de callback.
callback - uma função de callback opcional que será chamada depois que o trabalho assíncrono for concluído. Se você não especificar um callback, poderá aguardar a conclusão do XAsyncBlock com XAsyncGetStatus e, em seguida, obter os resultados.

Você deve criar um novo XAsyncBlock no heap para cada chamada assíncrona que fizer. O XAsyncBlock precisa existir até que o callback de conclusão do XAsyncBlock seja chamado; depois disso, ele pode ser excluído.

Importante: Um XAsyncBlock precisa permanecer na memória até que a tarefa assíncrona seja concluída. Se ele for alocado dinamicamente, poderá ser excluído dentro do callback de conclusão do XAsyncBlock.

Aguardando uma tarefa assíncrona

Você pode saber que uma tarefa assíncrona foi concluída de duas maneiras diferentes:

O callback de conclusão do XAsyncBlock é chamado.
Chame XAsyncGetStatus com true para aguardar até que ela seja concluída.

Com XAsyncGetStatus, a tarefa assíncrona é considerada concluída depois que o callback de conclusão do XAsyncBlock é executado; no entanto, o callback de conclusão do XAsyncBlock é opcional. Depois que a tarefa assíncrona for concluída, você poderá obter os resultados.

Obtendo o resultado da tarefa assíncrona

Para obter o resultado, a maioria das funções de API assíncronas tem uma função Result correspondente para receber o resultado da chamada assíncrona. No nosso código de exemplo, PFProfilesGetProfileAsync tem uma função PFProfilesGetProfileGetResult correspondente. Você pode usar essa função para recuperar o resultado da função e agir de acordo. Para obter detalhes completos sobre como recuperar resultados, consulte a documentação de cada função de API assíncrona.

O XTaskQueueHandle

O XTaskQueueHandle permite determinar qual thread executa a tarefa assíncrona e qual thread chama o callback de conclusão do XAsyncBlock. Você pode controlar qual thread executa essas operações definindo um modo de despacho. Há três modos de despacho disponíveis:

Manual - A fila manual não é despachada automaticamente. Cabe ao desenvolvedor despachá-la em qualquer thread que desejar. Isso pode ser usado para atribuir o lado de trabalho ou o lado de callback de uma chamada assíncrona a uma thread específica.
Thread Pool - Despacha usando um pool de threads. O pool de threads invoca as chamadas em paralelo, retirando da fila uma chamada para executar à medida que as threads do pool ficam disponíveis. O Thread Pool é o mais fácil de usar, mas oferece o menor controle sobre qual thread é usada.
Serialized Thread Pool - Despacha usando um pool de threads. O pool de threads invoca as chamadas em série, retirando da fila uma chamada para executar à medida que a única thread do pool fica disponível.
Immediate - Despacha imediatamente o trabalho enfileirado na thread a partir da qual ele foi enviado.

Para criar um novo XTaskQueueHandle, você precisa chamar XTaskQueueCreate. Por exemplo:

STDAPI XTaskQueueCreate(
    _In_ XTaskQueueDispatchMode workDispatchMode,
    _In_ XTaskQueueDispatchMode completionDispatchMode,
    _Out_ XTaskQueueHandle* queue
    ) noexcept;

Essa função recebe dois parâmetros XTaskQueueDispatchMode. Há três valores possíveis para XTaskQueueDispatchMode:

/// <summary>
/// Describes how task queue callbacks are processed.
/// </summary>
enum class XTaskQueueDispatchMode : uint32_t
{
    /// <summary>
    /// Callbacks are invoked manually by XTaskQueueDispatch
    /// </summary>
    Manual,

    /// <summary>
    /// Callbacks are queued to the system thread pool and will
    /// be processed in order by the thread pool across multiple thread
    /// pool threads.
    /// </summary>
    ThreadPool,
    
    /// <summary>
    /// Callbacks are queued to the system thread pool and
    /// will be processed one at a time.
    /// </summary>
    SerializedThreadPool,
    
    /// <summary>
    /// Callbacks are not queued at all but are dispatched
    /// immediately by the thread that submits them.
    /// </summary>
    Immediate
};

workDispatchMode determina o modo de despacho da thread que processa o trabalho assíncrono. completionDispatchMode determina o modo de despacho da thread que processa a conclusão da operação assíncrona. Depois de criar seu XTaskQueueHandle, basta adicioná-lo ao XAsyncBlock para controlar as threads das suas funções de trabalho e de conclusão. Quando terminar de usar o XTaskQueueHandle, normalmente quando o jogo estiver terminando, você poderá fechá-lo com XTaskQueueCloseHandle:

STDAPI_(void) XTaskQueueCloseHandle(
    _In_ XTaskQueueHandle queue
    ) noexcept;

Exemplo de chamada:

XTaskQueueCloseHandle(queue);

Despachando manualmente um XTaskQueueHandle

Se você usou o modo de despacho de fila manual para uma fila de trabalho ou de conclusão de um XTaskQueueHandle, precisará despachá-la manualmente. Digamos que um XTaskQueueHandle tenha sido criado com a fila de trabalho e a fila de conclusão definidas para despacho manual, assim:

XTaskQueueHandle queue = nullptr;
HRESULT hr = XTaskQueueCreate(
    XTaskQueueDispatchMode::Manual,
    XTaskQueueDispatchMode::Manual,
    &queue);

Para despachar o trabalho que recebeu XTaskQueueDispatchMode::Manual, chame a função XTaskQueueDispatch.

STDAPI_(bool) XTaskQueueDispatch(
    _In_ XTaskQueueHandle queue,
    _In_ XTaskQueuePort port,
    _In_ uint32_t timeoutInMs
    ) noexcept;

Exemplo de chamada:

HRESULT hr = XTaskQueueDispatch(queue, XTaskQueuePort::Completion, 0);

queue - a fila na qual o trabalho será despachado.
port - uma instância do enum XTaskQueuePort.
timeoutInMs - um uint32_t para o tempo limite em milissegundos.

Há dois tipos de callback definidos pelo enum XTaskQueuePort:

/// <summary>
/// Declares which port of a task queue to dispatch or submit
/// callbacks to.
/// </summary>
enum class XTaskQueuePort : uint32_t
{
    /// <summary>
    /// Work callbacks
    /// </summary>
    Work,

    /// <summary>
    /// Completion callbacks after work is done
    /// </summary>
    Completion
};

Quando chamar XTaskQueueDispatch

Para verificar quando a fila recebeu um novo item, você pode chamar XTaskQueueRegisterMonitor para definir um manipulador de eventos que informe ao seu código que há trabalhos ou conclusões prontos para serem despachados.

STDAPI XTaskQueueRegisterMonitor(
    _In_ XTaskQueueHandle queue,
    _In_opt_ void* callbackContext,
    _In_ XTaskQueueMonitorCallback* callback,
    _Out_ XTaskQueueRegistrationToken* token
    ) noexcept;

XTaskQueueRegisterMonitor recebe os seguintes parâmetros:

queue - a fila assíncrona para a qual você está enviando o callback.
callbackContext - um ponteiro para os dados que devem ser passados para o callback de envio.
callback - a função invocada quando um novo callback é enviado para a fila.
token - um token usado em uma chamada posterior a XTaskQueueUnregisterMonitor para remover o callback.

Por exemplo, aqui está uma chamada a XTaskQueueRegisterMonitor:

XTaskQueueRegisterMonitor(queue, nullptr, HandleAsyncQueueCallback, &m_callbackToken);

O callback XTaskQueueMonitorCallback correspondente pode ser implementado da seguinte forma:

void CALLBACK HandleAsyncQueueCallback(
    _In_opt_ void* context,
    _In_ XTaskQueueHandle queue,
    _In_ XTaskQueuePort port)
{
    switch (port)
    {
    case XTaskQueuePort::Work:
        {
            std::lock_guard<std::mutex> lock(g_workReadyMutex);
            g_workReady = true;
        }

        g_workReadyConditionVariable.notify_one(); // (std::condition_variable)
        break;
    }
}

Em seguida, em uma thread em segundo plano, você pode aguardar que essa variável de condição seja acionada e chamar XTaskQueueDispatch.

void BackgroundWorkThreadProc(XTaskQueueHandle queue)
{
    while (true)
    {
        {
            std::unique_lock<std::mutex> cvLock(g_workReadyMutex);
            g_workReadyConditionVariable.wait(cvLock, [] { return g_workReady; });

            if (g_stopBackgroundWork)
            {
                break;
            }

            g_workReady = false;
        }

        bool workFound = false;
        do
        {
            workFound = XTaskQueueDispatch(queue, XTaskQueuePort::Work, 0);
        } while (workFound);
    }
    
    XTaskQueueCloseHandle(queue);
}

XBOX Services

PlayFab

Fazendo chamadas assíncronas no SDK unificado do PlayFab

O XAsyncBlock

Aguardando uma tarefa assíncrona

Obtendo o resultado da tarefa assíncrona

O XTaskQueueHandle

Despachando manualmente um XTaskQueueHandle

Quando chamar XTaskQueueDispatch

Confira também

​O XAsyncBlock

​Aguardando uma tarefa assíncrona

​Obtendo o resultado da tarefa assíncrona

​O XTaskQueueHandle

​Despachando manualmente um XTaskQueueHandle

​Quando chamar XTaskQueueDispatch

​Confira também

O XAsyncBlock

Aguardando uma tarefa assíncrona

Obtendo o resultado da tarefa assíncrona

O XTaskQueueHandle

Despachando manualmente um XTaskQueueHandle

Quando chamar XTaskQueueDispatch

Confira também