Modelo de programación asincrónica

​

Modelo conceptual

​

Requisitos

1. Preferir llamadas sincrónicas en lugar de llamadas asincrónicas
2. Proporcionar operaciones asincrónicas con sondeo
3. Proporcionar operaciones asincrónicas con devoluciones de llamada
4. Proporcionar control sobre el subproceso en el que se ejecuta el trabajo asincrónico
5. Proporcionar control sobre el subproceso en el que se ejecutan las devoluciones de llamada de finalización

​

Tipos de API

• Seguras para subprocesos sensibles al tiempo: una API segura para subprocesos sensibles al tiempo es aquella que se puede llamar en un subproceso sensible al tiempo. Tenga en cuenta que, aunque esto normalmente significa que la API es trivial o muy rápida, el concepto clave es que las características de rendimiento de la API son coherentes. Siempre son sincrónicas y nunca necesitan tener una versión asincrónica. Estas API deben documentarse como seguras para tiempo sensible.
• No seguras para subprocesos sensibles al tiempo: no es seguro llamar a estas API desde el subproceso de representación. Sus características de rendimiento pueden variar considerablemente. La mayoría de las API pertenecen a esta categoría.
• Asincrónicas: estas API son de naturaleza asincrónica, como una llamada a un servicio web. Usan el patrón asincrónico descrito en este tema. Las API asincrónicas no son tan comunes en Microsoft Game Development Kit (GDK) como en el modelo de programación de XBOX One ERA: una API asincrónica suele ser de larga duración y cancelable. Excepto en algunos casos de uso específicos, las API asincrónicas tendrán una versión sincrónica no segura para tiempo crítico. La llamada a una API asincrónica siempre debe ser segura para tiempo crítico.
• Notificaciones: las notificaciones son de naturaleza periódica y no tienen un final definido. Están relacionadas con las API asincrónicas pero, debido a su naturaleza periódica, deben tener un aspecto y un comportamiento diferentes para los desarrolladores. Registrarse para una notificación siempre debe ser seguro para tiempo crítico.

​

Patrón de API asincrónica

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 de la API asincrónica

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

​

Control de la distribución del trabajo

• Grupo de subprocesos: las devoluciones de llamada puestas en cola en una cola de grupo de subprocesos se ejecutan en el grupo de subprocesos del sistema. El grupo de subprocesos invoca las llamadas en paralelo, tomando por turnos una llamada de la cola para ejecutarla a medida que los subprocesos del grupo quedan disponibles.
• Grupo de subprocesos serializado: las devoluciones de llamada se ponen en cola y se ejecutan en el grupo de subprocesos, pero de una en una.
• Manual: las devoluciones de llamada puestas en cola en una cola manual no se distribuyen automáticamente. Corresponde al desarrollador distribuirlas en el subproceso que desee.
• Inmediato: el modo de distribución inmediato no pone nada en cola. Ejecuta inmediatamente la llamada en el subproceso que envió la devolución de llamada.

​

Notificaciones

1. Asincrónica con sondeo
2. Asincrónica con devoluciones de llamada
3. Control sobre el subproceso en el que se producen las devoluciones de llamada

• Un método Register que toma los parámetros específicos de la llamada, una cola de tareas, un contexto void opcional y un puntero de devolución de llamada fuertemente tipado. El último parámetro es un parámetro out que devuelve un token.
• Un método Unregister que toma el contexto específico de la llamada y el token.
• El sondeo se admite agregando un método independiente no relacionado con la devolución de llamada de la notificación.

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 asincrónica

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. Llame a XAsyncBegin con el bloque asincrónico pasado por el autor de la llamada y proporcione una devolución de llamada que proporcione la implementación.
2. Realice el trabajo asincrónico de la llamada. Si necesita ejecutar el trabajo en un subproceso de trabajo, llame a XAsyncSchedule. Si puede realizar el trabajo usando primitivas asincrónicas del sistema operativo y configurar esas primitivas con la rapidez suficiente para seguir siendo seguro para tiempo crítico, esa opción es preferible.
3. Si necesita invocar otro trabajo asincrónico desde una devolución de llamada de subproceso de trabajo, puede devolver E_PENDING desde el trabajo. También puede llamar a XAsyncSchedule desde dentro de un trabajo para volver a programar trabajo adicional.
4. Cuando todo el trabajo esté completo, llame a XAsyncComplete.
5. Proporcione un contenedor fuertemente tipado alrededor de XAsyncGetResult para devolver los resultados.
6. Si su llamada asincrónica no tiene carga de datos, debe proporcionar un contenedor fuertemente tipado alrededor de XAsyncGetStatus y pasar cero como tamaño de búfer requerido a XAsyncComplete.

• Begin: se invoca un proveedor asincrónico con este código de operación durante XAsyncBegin. Si el proveedor implementa este código de operación, debe iniciar su tarea asincrónica llamando a XAsyncSchedule o mediante medios externos. Se llama a esta devolución de llamada de forma sincrónica en la cadena de llamadas de XAsyncBegin, por lo que nunca debe bloquearse.
• DoWork: se llama en los casos en que se llamó a XAsyncSchedule para programar el trabajo asincrónico mediante la cola de tareas. La función del proveedor realiza el trabajo que necesite. Cuando se completa, llama a XAsyncComplete con el código de resultado y el tamaño de la carga de datos, que puede ser cero si la llamada no tiene carga de datos. Si es necesario realizar más trabajo asincrónico, el proveedor puede programar ese trabajo y debe devolver E_PENDING.
• GetResult: se llama para capturar el resultado de la llamada. Dado que el tamaño de los datos se pasa a XAsyncComplete durante la finalización de la llamada, aquí no se necesita comprobar los argumentos: la biblioteca ha verificado todos los búferes y los tamaños de búfer.
• Cancel: se llama cuando el usuario cancela una llamada asincrónica. Si la llamada puede cancelarse, cancélela y llame a XAsyncComplete con E_ABORT como código de resultado.
• Cleanup: se llama cuando la llamada ha finalizado completamente, y el proveedor puede eliminar cualquier memoria 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);
}

​

Documentación de referencia de la API

• XAsync (contenido de la API)
  • Funciones
    • XAsyncGetStatus
    • XAsyncGetResultSize
    • XAsyncCancel
    • XAsyncCompletionRoutine
    • XAsyncRun
  • Estructuras
    • XAsyncBlock
• XAsyncProvider (contenido de la API)
  • Funciones
    • XAsyncGetResult
    • XAsyncBegin
    • XAsyncSchedule
    • XAsyncComplete
• XTaskQueue (contenido de la API)
  • Funciones
    • xtaskqueuecreate
    • xtaskqueuedispatch
• xgamesave (contenido de la API)
  • Funciones
    • XGameSaveGetRemainingQuotaAsync
    • XGameSaveGetRemainingQuotaResult

​

Consulte también