> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XTaskQueueDispatch

> XTaskQueueDispatch

# XTaskQueueDispatch

處理工作佇列中指定連接埠的一個項目。

## 語法

```cpp theme={null}
bool XTaskQueueDispatch(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         uint32_t timeoutInMs  
)  
```

### 參數

*queue*   \_In\_\
類型：XTaskQueueHandle

要在其上分派工作的佇列。

*port*   \_In\_\
類型：[XTaskQueuePort](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueueport.md)

要分派的連接埠。

*timeoutInMs*   \_In\_\
類型：uint32\_t

傳回 false 之前等候工作抵達的毫秒數。您可以傳遞 **INFINITE** 以無限期等候。

### 傳回值

類型：bool

如果此函式分派了呼叫，則傳回 true，否則傳回 false。如果佇列已終止，即使傳遞 **INFINITE** 作為逾時，此函式也會傳回 false。

## 備註

您可以傳遞逾時，這會使 **XTaskQueueDispatch** 等候佇列中有項目抵達。

如果工作佇列連接埠是以 [XTaskQueueDispatchMode::ThreadPool](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)、[XTaskQueueDispatchMode::SerializedThreadPool](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md) 或 [XTaskQueueDispatchMode::Immediate](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md) 分派模式建立，就會自動分派回呼。對於手動分派連接埠，您必須呼叫 **XTaskQueueDispatch**。任何分派模式都可以呼叫 **XTaskQueueDispatch**，但請注意，呼叫一律會在呼叫 **XTaskQueueDispatch** 的執行緒上分派。

![alert](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/note.gif?s=6c1a4c009b25ad5315c45ce51bc83983) **效能注意事項：**\
將項目加入佇列必須是無鎖定且無等候的，以符合上游程式碼的效能需求。下列 API 為無鎖定：

* [XTaskQueueSubmitCallback](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback.md)
* [XTaskQueueSubmitDelayedCallback](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitdelayedcallback.md)
* [XTaskQueueDispatch](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuedispatch.md)，前提是 *timeoutInMs* 傳遞 0

![alert](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/note.gif?s=6c1a4c009b25ad5315c45ce51bc83983) **效能注意事項：**\
[XTaskQueueDispatch](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuedispatch.md) 在處理工作連接埠中的項目時所花費的時間不固定，取決於正在執行的工作。
在某些情況下，呼叫端執行緒可能會封鎖，以等候其他系統工作完成。

下列範例示範如何使用 **XTaskQueueDispatch** 函式來處理工作佇列中的項目。

> [!NOTE]
>
> **SubmitCallback** 是在 [XTaskQueueSubmitCallback](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback.md) 函式的程式碼範例中定義的協助程式函式。

```cpp theme={null}
void CreatingTaskQueueWithManualThreads()
{
    // Create a manual task queue
    XTaskQueueHandle queue;
    HRESULT hr = XTaskQueueCreate(XTaskQueueDispatchMode::Manual, XTaskQueueDispatchMode::Manual, &queue);
    if (FAILED(hr))
    {
        printf("Creating queue failed: 0x%x\r\n", hr);
        return;
    }

    // We create threads to pump the queue: one for the work port
    // and one for the completion port.
    std::thread workThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Work, INFINITE));
    });

    std::thread completionThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Completion, INFINITE));
    });

    SubmitCallbacks(queue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    // Terminating the queue will cause a waiting DispatchTaskQueue to return
    // false.  
    XTaskQueueTerminate(queue, true, nullptr, nullptr);

    workThread.join();
    completionThread.join();
}
```

## 需求

**標頭：** XTaskQueue.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [清除工作佇列](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-cleanup-task-queue.md)
* [分派工作佇列](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-dispatch-task-queue.md)
* [XTaskQueue 程式庫概觀](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-libraries/async-library-xtaskqueue.md)
* [非同步程式設計模型](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-programming-model.md)
* [非同步程式設計的設計目標和改進](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-whitepaper.md)

## 另請參閱

[XTaskQueue 成員](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/xtaskqueue_members.md)\
[非同步程式設計模型](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-programming-model.md)\
[非同步工作佇列設計](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-task-queue-design.md)


## Related topics

- [XTaskQueueDispatchMode](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)
- [XTaskQueuePort](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/enums/xtaskqueueport.md)
- [在 XSAPI C API 中進行非同步呼叫](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/xbox-services-api/live-flatc-async-patterns.md)
- [在 PlayFab Unified SDK 中進行非同步呼叫](https://docs.xbox.com/zh-TW/services/playfab/sdks/unified-sdk/async-model.md)
- [進行非同步呼叫](https://docs.xbox.com/zh-TW/services/playfab/sdks/c/async.md)