Edit

Share via

RtwqAllocateSerialWorkQueue function (rtworkq.h)

  • Article

Creates a virtual work queue on top of another work queue that is guaranteed to serialize work items. The serial work queue wraps an existing multithreaded work queue. The serial work queue enforces a first-in, first-out (FIFO) execution order.

Syntax

HRESULT RtwqAllocateSerialWorkQueue(
  [in]  DWORD workQueueIdIn,
  [out] DWORD *workQueueIdOut
);

Parameters

[in] workQueueIdIn

The identifier of an existing work queue. This must be either a multithreaded queue or another serial work queue. Any of the following can be used:

  • The default work queue (RTWQ_STANDARD_WORKQUEUE). See RTWQ_WORKQUEUE_TYPE.
  • The platform multithreaded queue (RTWQ_MULTITHREADED_WORKQUEUE). See RTWQ_WORKQUEUE_TYPE.
  • A multithreaded queue returned by the RtwqLockSharedWorkQueue function.
  • A serial queue created by the RtwqAllocateSerialWorkQueue function.

[out] workQueueIdOut

Receives an identifier for the new serial work queue. Use this identifier when queuing work items.

Return value

This function can return one of these values.

Return code Description
S_OK
 The function succeeded.
E_FAIL
 The application exceeded the maximum number of work queues.
RTWQ_E_SHUTDOWN
 The application did not call RtwqStartup, or the application has already called RtwqShutdown.

Remarks

When you are done using the work queue, call RtwqUnlockWorkQueue.

Multithreaded queues use a thread pool, which can reduce the total number of threads in the pipeline. However, they do not serialize work items. A serial work queue enables the application to get the benefits of the thread pool, without needing to perform manual serialization of its own work items.

Requirements

Requirement Value
Minimum supported client Windows 8.1 [desktop apps only]
Minimum supported server Windows Server 2012 R2 [desktop apps only]
Target Platform Windows
Header rtworkq.h
Library Rtworkq.lib
DLL RTWorkQ.dll

See also

RTWQ_WORKQUEUE_TYPE