MFAllocateSerialWorkQueue

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(
         DWORD dwWorkQueue,
         DWORD *pdwWorkQueue
)  

Parameters

dwWorkQueue
Type: DWORD 

[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
Type: DWORD *

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

Return value

Type: HRESULT 

Return codes

Refer to Media Foundation return codes.

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.

Example

C++

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;
}  

Requirements

Header: Declared in mfapi.h.

Library: Use Mfplat.lib.