Share via

XTaskQueueDispatchMode

  • Article

Describes how task queue callbacks are processed.

Syntax

typedef enum class XTaskQueueDispatchMode  : uint32_t  
{  
    Manual,  
    ThreadPool,  
    SerializedThreadPool,  
    Immediate  
} XTaskQueueDispatchMode

Constants

Constant Description
Manual Callbacks are not automatically dispatched. Callbacks submitted to a port using this dispatch mode are queued, but must be dispatched manually by XTaskQueueDispatch.
Note: If you have a thread that pumps Windows messages:
  • Do not dispatch callbacks for the work port
  • If you dispatch callbacks for the completion port, you must continue to pump Windows messages for the thread

For more information, see Creating a manual task queue.
ThreadPool Callbacks submitted to a port using this dispatch mode are queued and automatically dispatched on the system thread queue. The task queue executes the calls in parallel, taking a call to execute from the task queue in turn as thread pool threads become available.
For more information about creating a thread pool task queue, see Creating a thread pool task queue.
SerializedThreadPool Callbacks submitted to a port using this dispatch mode are queued and automatically dispatched on the system thread queue. Unlike ThreadPool, the task queue executes the calls in serial, one at a time, on the thread pool.
Immediate Callbacks are not queued at all, but are executed immediately on the thread that submitted them. For an example that implements the immediate dispatch mode, see Creating a composite task queue.

Remarks

This enumeration is used by XTaskQueueCreate to specify the dispatch modes for the work and completion ports of a task queue.

The work port and completion port can use different dispatch modes. For example, you can use the thread pool dispatch mode for the work port to automatically queue & execute callbacks in parallel on the system thread queue, and use the manual dispatch mode for the completion port to manually queue & execute callbacks on the Windows message loop thread. For more information, see Using a task queue with a Windows message loop.

Requirements

Header: XTaskQueue.h

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

See also

XTaskQueue members
Asynchronous Programming Model
Async Task Queue Design