Compartilhar via

Modelo assíncrono

  • Artigo

A maioria das operações na API dos Serviços Web do Windows pode ser executada de forma síncrona ou assíncrona. Para chamar uma função de forma síncrona, passe um valor nulo para a estrutura WS_ASYNC_CONTEXT . Para especificar que uma função pode ser executada de forma assíncrona, passe uma WS_ASYNC_CONTEXT não nula para a função.

Quando chamada de forma assíncrona, uma função pode, no entanto, ser concluída de forma síncrona ou assíncrona. Se a função for concluída de forma síncrona, ela retornará um valor que indica o êxito final ou o erro e esse valor sempre será algo diferente de WS_S_ASYNC (consulte Valores retornados dos Serviços Web do Windows). Um valor retornado de WS_S_ASYNC, no entanto, indica que a função será concluída de forma assíncrona. Quando a função é concluída de forma assíncrona, um retorno de chamada é invocado para sinalizar a conclusão da operação. Esse retorno de chamada indica o êxito final ou o valor de erro. O retorno de chamada não será chamado se a operação for concluída de forma síncrona.

Para criar um contexto assíncrono, inicialize os campos callback e callbackState da estrutura WS_ASYNC_CONTEXT . O campo callbackState é usado para especificar um ponteiro para dados definidos pelo usuário que é passado para a função WS_ASYNC_CALLBACK .

O exemplo a seguir mostra a chamada de uma função de forma assíncrona passando um ponteiro para uma estrutura WS_ASYNC_CONTEXT que contém o retorno de chamada e um ponteiro para os dados de estado.

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

A estrutura WS_ASYNC_CONTEXT é usada pela função assíncrona somente durante a chamada de função (não durante a operação assíncrona), para que você possa declará-la com segurança na pilha.

Se outros parâmetros, além da estrutura WS_ASYNC_CONTEXT , forem passados para uma função assíncrona como ponteiros e a função for concluída de forma assíncrona, será responsabilidade do chamador manter os valores apontados por esses parâmetros ativos (não liberados) até que o retorno de chamada assíncrono seja invocado.

Há limitações em quais operações um retorno de chamada pode executar. Para obter mais informações sobre possíveis operações, consulte o WS_CALLBACK_MODEL.

Ao implementar uma função assíncrona, não invoque o retorno de chamada no mesmo thread que chamou a função assíncrona antes que a função assíncrona retorne ao chamador, pois isso interrompe o modelo assíncrono.

Ao implementar uma função que precisa executar uma série de operações assíncronas, considere usar a função auxiliar WsAsyncExecute .

O Exemplo de Função Assíncrona mostra como implementar e consumir funções que seguem o modelo assíncrono.

Iniciar uma operação de E/S assíncrona consome recursos do sistema. Se forem iniciadas operações de E/S suficientes, o sistema poderá ficar sem resposta. Para evitar isso, um aplicativo precisa limitar o número de operações assíncronas iniciadas.

O modelo assíncrono usa os seguintes elementos de API.

Callback Descrição
WS_ASYNC_CALLBACK O parâmetro de função de retorno de chamada usado com o modelo assíncrono.
WS_ASYNC_FUNCTION Usado com o WsAsyncExecute para especificar a próxima função a ser invocada em uma série de operações assíncronas.

 

Enumeração Descrição
WS_CALLBACK_MODEL Especifica o comportamento de threading de um retorno de chamada (por exemplo, um WS_ASYNC_CALLBACK).

 

Função Descrição
WsAsyncExecute Invoca um retorno de chamada definido pelo usuário que pode iniciar uma operação assíncrona e indicar uma função que deve ser chamada quando a operação assíncrona for concluída.

 

Estrutura Descrição
WS_ASYNC_CONTEXT Especifica o retorno de chamada assíncrono e um ponteiro para dados definidos pelo usuário, que serão passados para o retorno de chamada assíncrono.
WS_ASYNC_OPERATION Usado com o WsAsyncExecute para especificar a próxima função a ser invocada em uma série de operações assíncronas.
WS_ASYNC_STATE Usado por WsAsyncExecute para gerenciar o estado de uma operação assíncrona.

 

Exemplo de função assíncrona

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute