Modèle asynchrone

La plupart des opérations dans l’API des services web Windows peuvent être effectuées de manière synchrone ou asynchrone. Pour appeler une fonction de façon synchrone, passez une valeur Null pour la structure WS_ASYNC_CONTEXT. Pour spécifier qu’une fonction peut être effectuée de manière asynchrone, transmettez une WS_ASYNC_CONTEXT non null à la fonction.

Lorsqu’elle est appelée de façon asynchrone, une fonction peut néanmoins se terminer de façon synchrone ou asynchrone. Si la fonction se termine de façon synchrone, elle retourne une valeur qui indique la réussite ou l’erreur finale, et cette valeur est toujours autre que WS_S_ASYNC (voir valeurs de retour des services web Windows). Toutefois, une valeur de retour de WS_S_ASYNCindique que la fonction se termine de façon asynchrone. Une fois la fonction terminée de façon asynchrone, un rappel est appelé pour signaler l’achèvement de l’opération. Ce rappel indique la valeur finale de réussite ou d’erreur. Le rappel n’est pas appelé si l’opération se termine de façon synchrone.

Pour créer un contexte asynchrone, initialisez les champs de rappel et callbackState de la structure WS_ASYNC_CONTEXT. Le champ callbackState est utilisé pour spécifier un pointeur vers des données définies par l’utilisateur qui sont passées à la fonction WS_ASYNC_CALLBACK.

L’exemple suivant montre comment appeler une fonction de façon asynchrone en passant un pointeur à une structure WS_ASYNC_CONTEXT qui contient le rappel et un pointeur vers les données d’état.

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

La structure WS_ASYNC_CONTEXT est utilisée par la fonction asynchrone uniquement pour la durée de l’appel de fonction (et non pour la durée de l’opération asynchrone), afin de pouvoir la déclarer en toute sécurité sur la pile.

Si d’autres paramètres, outre la structure WS_ASYNC_CONTEXT, sont transmis à une fonction asynchrone en tant que pointeurs et que la fonction se termine de manière asynchrone, il incombe à l’appelant de conserver les valeurs pointées par ces paramètres vivant (non libérés) tant que le rappel asynchrone n’est pas appelé.

Il existe des limitations sur les opérations qu’un rappel peut effectuer. Pour plus d’informations sur les opérations possibles, consultez la WS_CALLBACK_MODEL.

Lorsque vous implémentez une fonction asynchrone, n’appelez pas le rappel sur le même thread que celui qui a appelé la fonction asynchrone avant que la fonction asynchrone ne soit retournée à l’appelant, car cela interrompt le modèle asynchrone.

Lors de l’implémentation d’une fonction qui doit exécuter une série d’opérations asynchrones, envisagez d’utiliser la fonction d’assistance WsAsyncExecute.

L’exemple de fonction asynchrone montre comment implémenter et consommer des fonctions qui suivent le modèle asynchrone.

Le démarrage d’une opération d’E/S asynchrone consomme des ressources système. Si suffisamment d’opérations d’E/S sont démarrées, le système peut ne pas répondre. Pour éviter cela, une application doit limiter le nombre d’opérations asynchrones qu’elle démarre.

Le modèle asynchrone utilise les éléments d’API suivants.

Rappel	Description
WS_ASYNC_CALLBACK	Paramètre de fonction de rappel utilisé avec le modèle asynchrone.
WS_ASYNC_FUNCTION	Utilisé avec le WsAsyncExecute pour spécifier la fonction suivante à appeler dans une série d’opérations asynchrones.

 

Énumération	Description
WS_CALLBACK_MODEL	Spécifie le comportement de thread d’un rappel (par exemple, un WS_ASYNC_CALLBACK).

 

Fonction	Description
WsAsyncExecute	Appelle un rappel défini par l’utilisateur qui peut lancer une opération asynchrone et indiquer une fonction qui doit être appelée lorsque l’opération asynchrone a été terminée.

 

Structure	Description
WS_ASYNC_CONTEXT	Spécifie le rappel asynchrone et un pointeur vers des données définies par l’utilisateur, qui seront transmises au rappel asynchrone.
WS_ASYNC_OPERATION	Utilisé avec le WsAsyncExecute pour spécifier la fonction suivante à appeler dans une série d’opérations asynchrones.
WS_ASYNC_STATE	Utilisé par WsAsyncExecute pour gérer l’état d’une opération asynchrone.

 

Rubriques connexes

exemple de fonction asynchrone

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute