Realización de llamadas asincrónicas en el SDK unificado de PlayFab

Una API asincrónica es una API que se devuelve rápidamente pero 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 modo que una sección del montón solo la toque 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 el juego controle, actualizar el estado compartido con el resultado de una tarea asincrónica requiere sincronización de subprocesos. El SDK unificado de PlayFab expone una API asincrónica de C que ofrece a los desarrolladores control directo de los subprocesos al realizar una llamada asincrónica a la API. Este es un ejemplo básico de una 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, necesita entender cómo usar XAsyncBlock y XTaskQueueHandle. XAsyncBlock transporta toda la información relativa a la tarea asincrónica y 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 una parte del trabajo. Si este parámetro no está establecido, 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 se complete el XAsyncBlock con XAsyncGetStatus y luego obtener los resultados.

Debería crear un nuevo XAsyncBlock en el montón por cada llamada asincrónica que realice. El XAsyncBlock debe existir hasta que se llame a la devolución de llamada de finalización del XAsyncBlock, y después se puede eliminar.

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

Espera de una tarea asincrónica

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

Se llama a la devolución de llamada de finalización del 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 del XAsyncBlock; sin embargo, la devolución de llamada de finalización del 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 correspondiente PFProfilesGetProfileGetResult. 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 del 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 se puede usar para asignar el lado de trabajo o el lado de devolución de llamada de una llamada asincrónica a un subproceso específico.
Thread Pool: distribuye 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 ofrece el menor control sobre qué subproceso se usa.
Serialized Thread Pool: distribuye 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, necesita 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 para el subproceso que controla el trabajo asincrónico. completionDispatchMode determina el modo de distribución para el subproceso que controla la finalización de la operación asincrónica. Una vez que haya creado su XTaskQueueHandle, simplemente agréguelo al XAsyncBlock para controlar los subprocesos de sus funciones de trabajo y de finalización. Cuando haya terminado 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 distribuir 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 manera:

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

Para distribuir el trabajo al que se 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: en qué cola 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 que se invoca 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;
    }
}

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

XBOX Services

PlayFab

Realización de llamadas asincrónicas en el SDK unificado de PlayFab

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

Consulte también

​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

​Consulte también

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

Consulte también