Model asynchroniczny

Większość operacji w interfejsie API usług sieci Web systemu Windows może być wykonywana synchronicznie lub asynchronicznie. Aby wywołać funkcję synchronicznie, przekaż wartość null dla struktury WS_ASYNC_CONTEXT. Aby określić, że funkcja może być wykonywana asynchronicznie, przekaż WS_ASYNC_CONTEXT inną niż null do funkcji.

Po wywołaniu asynchronicznym funkcja może jednak wykonać synchronicznie lub asynchronicznie. Jeśli funkcja zostanie ukończona synchronicznie, zwraca wartość wskazującą ostateczny sukces lub błąd, a ta wartość jest zawsze czymś innym niż WS_S_ASYNC (zobacz Wartości zwracane usług sieci Web systemu Windows). Wartość zwracana WS_S_ASYNCwskazuje jednak, że funkcja zostanie ukończona asynchronicznie. Gdy funkcja zostanie ukończona asynchronicznie, wywołanie zwrotne jest wywoływane do sygnalizatora ukończenia operacji. To wywołanie zwrotne wskazuje ostateczną wartość powodzenia lub błędu. Wywołanie zwrotne nie jest wywoływane, jeśli operacja zostanie ukończona synchronicznie.

Aby utworzyć kontekst asynchroniczny, zainicjuj wywołania zwrotnego i pola callbackState struktury WS_ASYNC_CONTEXT. Pole callbackState służy do określania wskaźnika dla danych zdefiniowanych przez użytkownika, które są przekazywane do funkcji WS_ASYNC_CALLBACK.

W poniższym przykładzie pokazano wywołanie funkcji asynchronicznie przez przekazanie wskaźnika do struktury WS_ASYNC_CONTEXT zawierającej wywołanie zwrotne i wskaźnik do danych stanu.

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

Struktura WS_ASYNC_CONTEXT jest używana przez funkcję asynchroniczną tylko przez czas trwania wywołania funkcji (nie przez czas trwania operacji asynchronicznej), dzięki czemu można bezpiecznie zadeklarować ją na stosie.

Jeśli inne parametry, oprócz struktury WS_ASYNC_CONTEXT, są przekazywane do funkcji asynchronicznej jako wskaźników, a funkcja kończy asynchronicznie, jest to odpowiedzialność obiektu wywołującego, aby zachować wartości wskazywane przez te parametry aktywne (nie zwalniane) do momentu wywołania asynchronicznego wywołania zwrotnego.

Istnieją ograniczenia dotyczące operacji, które może wykonywać wywołanie zwrotne. Aby uzyskać więcej informacji na temat możliwych operacji, zobacz WS_CALLBACK_MODEL.

Podczas implementowania funkcji asynchronicznej nie należy wywoływać wywołania zwrotnego w tym samym wątku, który nazwał funkcję asynchroniczną przed zwróceniem funkcji asynchronicznej do wywołującego, ponieważ zakłóca to model asynchroniczny.

Podczas implementowania funkcji, która musi wykonywać serię operacji asynchronicznych, rozważ użycie funkcji pomocnika WsAsyncExecute.

Przykład funkcji asynchronicznej pokazuje, jak implementować i korzystać z funkcji, które są zgodne z modelem asynchronicznym.

Uruchomienie asynchronicznej operacji we/wy zużywa zasoby systemowe. Jeśli uruchomiono wystarczającą liczbę operacji we/wy, system może nie odpowiadać. Aby temu zapobiec, aplikacja musi ograniczyć liczbę uruchamianych przez nią operacji asynchronicznych.

Model asynchroniczny używa następujących elementów interfejsu API.

Tematy pokrewne

Przykład funkcji asynchronicznej

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute