Realización de llamadas asincrónicas - XBOX Game Development Documentation

Una API asincrónica es una API que devuelve rápidamente el control, pero que inicia una tarea asincrónica y el resultado se devuelve una vez finalizada la tarea. Tradicionalmente, los juegos han tenido poco control sobre qué subproceso ejecuta la tarea asincrónica y qué subproceso devuelve los resultados al usar una devolución de llamada de finalización. Algunos juegos están diseñados de manera que una sección del montón solo la toca un único subproceso para evitar cualquier necesidad de sincronización de subprocesos. Si la devolución de llamada de finalización no se llama desde un subproceso que controle el juego, actualizar el estado compartido con el resultado de una tarea asincrónica requiere sincronización de subprocesos. El SDK de PlayFab Services expone una API de C asincrónica que da a los desarrolladores control directo de los subprocesos al realizar una llamada a una API asincrónica, como PFAuthenticationLoginWithCustomIDAsync, PFDataGetFilesAsync o PFProfilesGetProfileAsync. Este es un ejemplo básico de llamada a 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 comprender este patrón de llamada, debe entender cómo se usan XAsyncBlock y XTaskQueueHandle. XAsyncBlock contiene toda la información relativa a la tarea asincrónica y a la devolución de llamada de finalización. XTaskQueueHandle le permite determinar qué subproceso ejecuta la tarea asincrónica y qué subproceso llama a la devolución de llamada de finalización de XAsyncBlock.

XAsyncBlock

Veamos XAsyncBlock en detalle. Es una estructura definida de la siguiente manera:

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

XAsyncBlock contiene:

queue: un XTaskQueueHandle, que es un identificador que representa información sobre dónde ejecutar un fragmento de trabajo. Si no se establece este parámetro, se usa una cola predeterminada.
context: le permite pasar datos a la función de devolución de llamada.
callback: una función de devolución de llamada opcional a la que se llamará una vez realizado el trabajo asincrónico. Si no especifica una devolución de llamada, puede esperar a que XAsyncBlock se complete con XAsyncGetStatus y, a continuación, obtener los resultados.

Debe crear un nuevo XAsyncBlock en el montón para cada llamada asincrónica que realice. El XAsyncBlock debe existir hasta que se llame a la devolución de llamada de finalización de XAsyncBlock; después puede eliminarse.

Importante: Un XAsyncBlock debe permanecer en memoria hasta que se complete la tarea asincrónica. Si se asigna dinámicamente, puede eliminarse dentro de la devolución de llamada de finalización de XAsyncBlock.

Espera de una tarea asincrónica

Puede saber que una tarea asincrónica se ha completado de dos formas diferentes:

Se llama a la devolución de llamada de finalización de XAsyncBlock.
Llame a XAsyncGetStatus con true para esperar hasta que se complete.

Con XAsyncGetStatus, la tarea asincrónica se considera completada después de que se ejecute la devolución de llamada de finalización de XAsyncBlock; sin embargo, la devolución de llamada de finalización de XAsyncBlock es opcional. Una vez completada la tarea asincrónica, puede obtener los resultados.

Obtención del resultado de la tarea asincrónica

Para obtener el resultado, la mayoría de las funciones de API asincrónicas tienen una función Result correspondiente para recibir el resultado de la llamada asincrónica. En nuestro código de ejemplo, PFProfilesGetProfileAsync tiene una función PFProfilesGetProfileGetResult correspondiente. Puede usar esta función para recuperar el resultado de la función y actuar en consecuencia. Para obtener todos los detalles sobre la recuperación de resultados, consulte la documentación de cada función de API asincrónica.

XTaskQueueHandle

XTaskQueueHandle le permite determinar qué subproceso ejecuta la tarea asincrónica y qué subproceso llama a la devolución de llamada de finalización de XAsyncBlock. Puede controlar qué subproceso realiza estas operaciones estableciendo un modo de distribución. Hay tres modos de distribución disponibles:

Manual: la cola manual no se distribuye automáticamente. Corresponde al desarrollador distribuirlas en el subproceso que quiera. Esto puede usarse para asignar el lado de trabajo o el de devolución de llamada de una llamada asincrónica a un subproceso específico.
Thread Pool: la distribución se realiza mediante un grupo de subprocesos. El grupo de subprocesos invoca las llamadas en paralelo, tomando por turno una llamada de la cola para ejecutarla a medida que los subprocesos del grupo quedan disponibles. Thread Pool es el más fácil de usar, pero le da la menor cantidad de control sobre qué subproceso se usa.
Serialized Thread Pool: la distribución se realiza mediante un grupo de subprocesos. El grupo de subprocesos invoca las llamadas en serie, tomando por turno una llamada de la cola para ejecutarla a medida que el único subproceso del grupo queda disponible.
Immediate: distribuye inmediatamente el trabajo en cola en el subproceso desde el que se envió.

Para crear un nuevo XTaskQueueHandle, debe llamar a XTaskQueueCreate. Por ejemplo:

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

Esta función toma dos parámetros XTaskQueueDispatchMode. Hay tres valores posibles 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 el modo de distribución del subproceso que gestiona el trabajo asincrónico. completionDispatchMode determina el modo de distribución del subproceso que gestiona la finalización de la operación asincrónica. Una vez creado su XTaskQueueHandle, simplemente agréguelo al XAsyncBlock para controlar los subprocesos de sus funciones de trabajo y finalización. Cuando termine de usar el XTaskQueueHandle, normalmente cuando el juego está finalizando, puede cerrarlo con XTaskQueueCloseHandle:

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

Ejemplo de llamada:

XTaskQueueCloseHandle(queue);

Distribución manual de un XTaskQueueHandle

Si usó el modo de distribución de cola manual para una cola de trabajo o de finalización de un XTaskQueueHandle, debe realizar la distribución manualmente. Supongamos que se creó un XTaskQueueHandle en el que tanto la cola de trabajo como la cola de finalización están configuradas para distribuirse manualmente, de esta forma:

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

Para distribuir el trabajo al que se le ha asignado XTaskQueueDispatchMode::Manual, llame a la función XTaskQueueDispatch.

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

Ejemplo de llamada:

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

queue: la cola en la que distribuir el trabajo.
port: una instancia de la enumeración XTaskQueuePort.
timeoutInMs: un uint32_t para el tiempo de espera en milisegundos.

Hay dos tipos de devolución de llamada definidos por la enumeración 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
};

Cuándo llamar a XTaskQueueDispatch

Para comprobar cuándo la cola ha recibido un nuevo elemento, puede llamar a XTaskQueueRegisterMonitor para establecer un controlador de eventos que informe a su código de que hay trabajo o finalizaciones listos para distribuirse.

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

XTaskQueueRegisterMonitor toma los siguientes parámetros:

queue: la cola asincrónica para la que envía la devolución de llamada.
callbackContext: un puntero a los datos que deben pasarse a la devolución de llamada de envío.
callback: la función invocada cuando se envía una nueva devolución de llamada a la cola.
token: un token que se usa en una llamada posterior a XTaskQueueUnregisterMonitor para quitar la devolución de llamada.

Por ejemplo, esta es una llamada a XTaskQueueRegisterMonitor:

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

La devolución de llamada XTaskQueueMonitorCallback correspondiente podría implementarse de la siguiente manera:

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

Después, en un subproceso en segundo plano, puede escuchar esta variable de condición para reactivarse y llamar a 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);
}

Referencia

Documentación de referencia de la API

​XAsyncBlock

​Espera de una tarea asincrónica

​Obtención del resultado de la tarea asincrónica

​XTaskQueueHandle

​Distribución manual de un XTaskQueueHandle

​Cuándo llamar a XTaskQueueDispatch

​Referencia