CreateDispatcherQueueController function (dispatcherqueue.h)

Creates a DispatcherQueueController. Use the created DispatcherQueueController to create and manage the lifetime of a DispatcherQueue to run queued tasks in priority order on the dispatcher queue's thread.

Syntax

HRESULT CreateDispatcherQueueController(
  [in]  DispatcherQueueOptions     options,
  [out] PDISPATCHERQUEUECONTROLLER *dispatcherQueueController
);

Parameters

[in] options

The threading affinity and type of COM apartment for the created DispatcherQueueController. See remarks for details.

[out] dispatcherQueueController

The created dispatcher queue controller.

Important  The DispatcherQueueController is a WinRT object.
 

Return value

S_OK for success; otherwise a failure code.

Remarks

Introduced in Windows 10, version 1709.

If options.threadType is DQTYPE_THREAD_DEDICATED, then this function creates a thread, initializes it with the specified COM apartment, and associates a DispatcherQueue with that thread. The dispatcher queue event loop runs on the new dedicated thread until the dispatcher queue is explicitly shut down. To avoid thread and memory leaks, call DispatcherQueueController.ShutdownQueueAsync when you are finished with the dispatcher queue.

If options.threadType is DQTYPE_THREAD_CURRENT, then a DispatcherQueue is created and associated with the current thread. An error results if there is already a DispatcherQueue associated with the current thread. The current thread must pump messages to allow the dispatcher queue to dispatch tasks. Before the current thread exits, it must call DispatcherQueueController.ShutdownQueueAsync, and continue pumping messages until the IAsyncAction completes.

This call does not return until the DispatcherQueueController and new thread (if any) are created.

Important  The DispatcherQueueController, and its associated DispatcherQueue, are WinRT objects. See their documentation for usage details.
 

Requirements

Requirement Value
Target Platform Windows
Header dispatcherqueue.h
Library CoreMessaging.lib
DLL CoreMessaging.dll

See also

DispatcherQueue

DispatcherQueueController