Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

MFAllocateSerialWorkQueue function

Creates a 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 MFAllocateSerialWorkQueue(
  _In_   DWORD dwWorkQueue,
  _Out_  DWORD *pdwWorkQueue
);

Parameters

dwWorkQueue [in]

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 (MFASYNC_CALLBACK_QUEUE_STANDARD)
  • The platform multithreaded queue (MFASYNC_CALLBACK_QUEUE_MULTITHREADED)
  • A multithreaded queue returned by the MFLockSharedWorkQueue function.
  • A serial queue created by the MFAllocateSerialWorkQueue function.
pdwWorkQueue [out]

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 codeDescription
S_OK

The function succeeded.

E_FAIL

The application exceeded the maximum number of work queues.

MF_E_SHUTDOWN

The application did not call MFStartup, or the application has already called MFShutdown.

 

Remarks

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

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.

Reply Mode

A serializer queue can also work in "reply" mode. If the caller’s IMFAsyncCallback::GetParameters method returns the MFASYNC_REPLY_CALLBACK flag, the serializer queue does not automatically advance to the next work item. Instead, the queue waits for a reply from the caller. The caller signals the reply by invoking the asynchronous result object that the work queue passes to the Invoke method. The following code illustrates how the caller signals the work queue.


HRESULT CCallback::Invoke(IMFAsyncResult *pResult)
{
    DoSomeWork();
    
    // Reply to the work queue that you are done.
    MFInvokeCallback(pResult);

    // Note: This call to MFInvokeCallback does not have to occur inside the
    // Invoke method. You could call MFInvokeCallback at a later time. 

    return S_OK;
}
HRESULT CCallback::GetParameters(DWORD *pdwFlags, DWORD *pdwQueue)
{
    *pdwFlags = MFASYNC_REPLY_CALLBACK;
    *pdwQueue = m_QueueId;
    return S_OK;
}


Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Header

Mfapi.h

DLL

Mfplat.dll

See also

Work Queue and Threading Improvements

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.