Asynchronous I/O Processing

It is important that your ISAPI extensions support asynchronous operations because that frees server pool threads to complete I/O operations. In addition, the IIS server engine already has built-in support to manage asynchronous I/O operations using the completion ports and server thread pool. ISAPI 1.0 only supported synchronous I/O operations through the ReadClient and WriteClient callback functions.

There are two basic types of async processing.You can implement WriteClient as an async process by setting the dwReserved parameter to HSE_IO_ASYNC. ReadClient and TransmitFile use the ServerSupportFunction to indicate asynchronous processing. For TransmitFile this is accomplished by calling the ServerSupportFunction with the dwHSERequest parameter set to HSE_REQ_TRANSMIT_FILE. For ReadClient the dwHSERequest parameter is set to HSE_REQ_ASYNC_READ_CLIENT.

ISAPI 2.0 and later versions support asynchronous write operations using the existing WriteClient callback function with a special flag that indicates the operation has to be performed asynchronously. In addition, these versions of ISAPI provide a mechanism to request the server transmit a file using the Win32 API TransmitFile. Only one asynchronous I/O operation can be in process at a time. If your ISAPI extension begins an asynchronous I/O operation, you should wait until the operation completes before starting another one.

    The following steps outline the order of events for asynchronous processing

1. IIS I/O thread calls the ISAPI extension with an ECB.
2. Extension returns HSE_STATUS_PENDING and puts the ECB in a worker queue.
3. Extension starts or re-uses a worker thread for the ECB and adds a ServerSupportFunction to the ECB with the dwHSERequest parameter set to HSE_REQ_IO_COMPLETION. The ECB is put on the worker thread.
4. The worker thread performs the required work using an async processing function.
5. When the I/O completes IIS calls the Async IO callback function with the context & IO status (bytes & error code). In the callback the ISAPI DLL may do other calls to either WriteClient or ServerSupportFunction until there are no more bytes waiting to be read or written.
6. When the worker thread is finished processing, it calls the ServerSupportFunction with the dwHSERequest parameter set to HSE_REQ_DONE_WITH_SESSION. When IIS receives this callback, it destroys the ECB.

Note  There is exactly one ECB for each ISAPI request. ECBs may be recycled for subsequent requests (only after the completion of the entire request). After calling the ServerSupportFunction with HSE_REQ_DONE_WITH_SESSION the extension should no longer use the ECB for which the call was made.