Dispatching Methods for I/O Requests

When a driver calls WdfIoQueueCreate to create an I/O queue, it specifies a dispatching method for the queue. The framework provides three dispatching methods: sequential, parallel, and manual. The driver can specify any of these dispatching methods for any I/O queue, including a device's default I/O queue.

The driver sets a queue's dispatching method by specifying a WDF_IO_QUEUE_DISPATCH_TYPE-typed value in the queue's WDF_IO_QUEUE_CONFIG structure.

For example uses of each dispatching method, see Example Uses of I/O Queues.

Sequential Dispatching

If your driver or device can process only one I/O request from a queue at a time, you should set up the device's I/O queues to use sequential dispatching, which is also called synchronous dispatching. With this type of dispatching, the framework delivers requests to the driver one at a time. The framework does not deliver the next request until the driver completes, cancels, or requeues the previous request.

After the framework delivers a request to one of the driver's request handlers, the driver processes the request. If the driver forwards the request to a general I/O target, it typically calls one of the I/O target object's synchronous methods. For more information about these methods, see Sending I/O Requests Synchronously. The driver must eventually complete or cancel every request that it receives from an I/O queue.

A driver that has set up an I/O queue for sequential dispatching can call WdfIoQueueRetrieveNextRequest or WdfIoQueueRetrieveRequestByFileObject to obtain another request from the queue before the last received request has been completed or canceled. You might want to do this in a function driver, so that the driver can start the next hardware operation while the driver's EvtInterruptDpc callback function is still processing data from the previous hardware operation.

If you create several I/O queues and set them all up for sequential dispatching, the framework dispatches requests from each queue sequentially, but the queues run in parallel. If your driver or device can process only one request at a time of any type, you must use a single I/O queue with an EvtIoDefault callback function.

Parallel Dispatching

If your driver and device can process multiple I/O requests simultaneously, you can set up the device's I/O queues to use parallel dispatching so that the driver can process the requests asynchronously. This dispatching method is also called asynchronous dispatching.

If a driver sets up an I/O queue to use parallel dispatching, the framework delivers I/O requests to the driver as soon as they are available in the queue. The result is that the driver might have to process several requests at once.

Each time one of the driver's request handlers receives a request, the driver must process the request and then complete the request. If the driver forwards the request to a general I/O target, it typically calls one of the I/O target object's asynchronous methods. For more information about these methods, see Sending I/O Requests Asynchronously. The driver must eventually complete or cancel every request that it receives from an I/O queue.

A driver that uses parallel dispatching can call WdfIoQueueStop or WdfIoQueueStopSynchronously to temporarily stop a queue, and then call WdfIoQueueStart to restart the queue.

Manual Dispatching

If you want your driver to have complete control over the delivery of I/O requests, you can set up a device's I/O queue to use manual dispatching, which means that the framework does not deliver requests to the driver unless the driver explicitly asks for one.

To obtain a request from a manual queue, the driver can call WdfIoQueueRetrieveNextRequest or WdfIoQueueRetrieveRequestByFileObject in a loop that polls the queue. Alternatively, the driver can call WdfIoQueueReadyNotify to register a callback function that the framework will call when one or more requests are available in the queue. After the framework calls the callback function, the driver can call WdfIoQueueRetrieveNextRequest or WdfIoQueueRetrieveRequestByFileObject in a loop to retrieve the requests.

After the driver obtains a request from the queue, it must process the request. The driver must eventually complete or cancel each request.