Writing Asynchronous Web Applications
This documentation is archived and is not being maintained.

Writing Asynchronous Web Applications 

To allow your request handler to write to the client asynchronously

  • Add one of the following macros to your request handler's class definition:

    Macro Description

    DECLARE_ASYNC_HANDLER

    Use this macro if buffered content is to be written asynchronously.

    DECLARE_ASYNC_HANDLER_EX

    Use this macro if you need to make explicit calls to asynchronous methods.

    NoteNote

    You do not need to write asynchronously just because you have prepared your request handler using one of these macros. However, if you will never write asynchronously, you should not use these macros because they impose a small performance cost.

To write to the client asynchronously

  1. Optionally call one of the methods for writing to the client asynchronously, such as TransmitFile.

  2. Return one of the following values from your request handler's HandleRequest method:

    Return value Description

    HTTP_SUCCESS_ASYNC

    Writes buffered content to the client asynchronously.

    ATL Server code calls HandleRequest or a replacement method again when the buffer has been flushed.

    HTTP_SUCCESS_ASYNC_DONE

    Writes buffered content to the client asynchronously.

    If this value is returned from HandleRequest or ValidateAndExchange, ATL Server code closes the connection with the client when the buffer has been flushed.

    If this value is returned from a replacement method, the ATL Server code moves on to the next token in the server response file.

    HTTP_SUCCESS_ASYNC_NOFLUSH

    User code has initiated an asynchronous call.

    ATL Server code calls HandleRequest or a replacement method again when the call is complete.

    HTTP_SUCCESS_ASYNC_NOFLUSH_DONE

    User code has initiated an asynchronous call.

    If this value is returned from HandleRequest or ValidateAndExchange, ATL Server code closes the connection with the client when the call is complete.

    If this value is returned from a replacement method, the ATL Server code moves on to the next token in the server response file.

If you write to the client asynchronously, you must have prepared your request handler by including ATLS_FLAG_ASYNC in the flags returned by GetHandlerFlags and by including ATLSRV_INIT_USEASYNC in the flags returned by GetFlags. Both DECLARE_ASYNC_HANDLER and DECLARE_ASYNC_HANDLER_EX will do this for you in IRequestHandlerImpl-derived classes.

In addition, if you want to enable explicit asynchronous writes, you must include ATLSRV_INIT_USEASYNC_EX in the flags returned by GetFlags. Only DECLARE_ASYNC_HANDLER_EX will do this for you in IRequestHandlerImpl-derived classes. (There is a separate flag for this because it requires extra synchronization to ensure that two calls to HandleRequest are not made at the same time.)

CRequestHandlerT enables all these values to be returned from replacement methods (except when they are used as conditional handlers called by while and if tags).

If HTTP_SUCCESS_ASYNC_DONE or HTTP_SUCCESS_ASYNC_NOFLUSH_DONE is returned from a replacement method, when processing resumes it will pick up from the next token in the stencil after the tag that called the replacement method.

If HTTP_SUCCESS_ASYNC or HTTP_SUCCESS_ASYNC_NOFLUSH is returned from a replacement method, the same method will be called again when processing resumes.

The asynchronous callback checks to see if the request is done based on whether the handler returned HTTP_SUCCESS_ASYNC_DONE or HTTP_SUCCESS_ASYNC_NOFLUSH_DONE from HandleRequest.

NoteNote

Request handlers that use asynchronous functions must not store pointers to per-thread services as data members. Although request handlers are only ever accessed by a single thread at a time, a request handler that returns one of the HTTP_CODEs for asynchronous behavior can be accessed from multiple threads during the course of its life. Per-thread services must only ever be used from a single thread.

Developers should test all Web server code under stress on a multiprocessor machine. The load on the server must be high enough that multiple threads are actually being used simultaneously. This type of testing is especially important for asynchronous applications that are more sensitive to multithreading issues.

See Also

Show:
© 2016 Microsoft