Поделиться через

Асинхронная модель

  • Статья

Большинство операций в API веб-служб Windows можно выполнять синхронно или асинхронно. Чтобы вызвать функцию синхронно, передайте значение NULL для структуры WS_ASYNC_CONTEXT. Чтобы указать, что функция может выполняться асинхронно, передайте в функцию ненулевое WS_ASYNC_CONTEXT.

При асинхронном вызове функция может завершиться синхронно или асинхронно. Если функция завершается синхронно, она возвращает значение, указывающее на окончательный успех или ошибку, и это значение всегда является чем-то другим, кроме WS_S_ASYNC (см. раздел возвращаемых значений веб-служб Windows). Однако возвращаемое значение WS_S_ASYNCуказывает, что функция будет выполняться асинхронно. Когда функция завершается асинхронно, обратный вызов вызывается для сигнала о завершении операции. Этот обратный вызов указывает окончательное значение успешного выполнения или ошибки. Обратный вызов не вызывается, если операция завершается синхронно.

Чтобы создать асинхронный контекст, инициализировать поля обратного вызова и callbackState структуры WS_ASYNC_CONTEXT. Поле callbackState используется для указания указателя на определяемые пользователем данные, передаваемые в функцию WS_ASYNC_CALLBACK.

В следующем примере показан вызов функции асинхронно путем передачи указателя на структуру WS_ASYNC_CONTEXT, содержащую обратный вызов и указатель на данные состояния.

HRESULT ExampleAsyncFunction(WS_ASYNC_CONTEXT* asyncContext);
void ExampleAsyncFunction()
{
    // Set up the WS_ASYNC_CONTEXT structure.
    MyState* myState = ...;  \\ Declare a pointer to user-defined data.
    WS_ASYNC_CONTEXT asyncContext;
    asyncContext.callback = MyCallback;  \\ Set the callback.
    asyncContext.callbackState = myState; \\ Set the pointer to the user-defined data.

    // Start the asynchronous operation
    HRESULT hr = SomeFunction(&asyncContext);

    if (hr == WS_S_ASYNC)
    {
        // The operation is completing asynchronously.  The callback is called 
        // when the operation is complete.
    }
    else
    {
        // The operation completed synchronously.  The callback is not called.
    }
}
void CALLBACK MyCallback(HRESULT hr, WS_CALLBACK_MODEL callbackModel, void* callbackState)
{
    MyState* myState = (MyState*)callbackState;

    // The operation completed asynchronously.
}

Структура WS_ASYNC_CONTEXT используется асинхронной функцией только в течение длительности вызова функции (не в течение асинхронной операции), поэтому ее можно безопасно объявить в стеке.

Если любые другие параметры, кроме структуры WS_ASYNC_CONTEXT, передаются в асинхронную функцию в качестве указателей и функция завершается асинхронно, вызывающий отвечает за сохранение значений, указывающих на эти параметры (не освобождается), пока асинхронный обратный вызов не будет вызван.

Существуют ограничения на то, какие операции могут выполнять обратный вызов. Дополнительные сведения о возможных операциях см. в WS_CALLBACK_MODEL.

При реализации асинхронной функции не вызывайте обратный вызов в том же потоке, который вызывал асинхронную функцию, прежде чем асинхронная функция вернулась вызывающей функции, так как это нарушает асинхронную модель.

При реализации функции, необходимой для выполнения ряда асинхронных операций, рассмотрите возможность использования вспомогательной функции WsAsyncExecute.

В примере асинхронной функции показано, как реализовать и использовать функции, которые соответствуют асинхронной модели.

Запуск асинхронной операции ввода-вывода использует системные ресурсы. Если запущены достаточно операций ввода-вывода, система может перестать отвечать. Чтобы предотвратить это, приложению необходимо ограничить количество асинхронных операций, которые он запускает.

Асинхронная модель использует следующие элементы API.

Обратный вызов Описание
WS_ASYNC_CALLBACK Параметр функции обратного вызова, используемый с асинхронной моделью.
WS_ASYNC_FUNCTION Используется с WsAsyncExecute, чтобы указать следующую функцию для вызова в серии асинхронных операций.

 

Перечисление Описание
WS_CALLBACK_MODEL Указывает поведение потоков обратного вызова (например, WS_ASYNC_CALLBACK).

 

Функция Описание
WsAsyncExecute Вызывает определяемый пользователем обратный вызов, который может инициировать асинхронную операцию и указывать функцию, которая должна вызываться при завершении асинхронной операции.

 

Структура Описание
WS_ASYNC_CONTEXT Указывает асинхронный обратный вызов и указатель на определяемые пользователем данные, которые будут переданы в асинхронный обратный вызов.
WS_ASYNC_OPERATION Используется с WsAsyncExecute, чтобы указать следующую функцию для вызова в серии асинхронных операций.
WS_ASYNC_STATE Используется WsAsyncExecute для управления состоянием асинхронной операции.

 

Пример асинхронной функции

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute