> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.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](/zh-TW/reference/system/xtaskqueue/enums/xtaskqueueport)

要分派的連接埠。

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

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

### 傳回值

類型：bool

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

## 備註

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

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

<img src="https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/note.gif?s=6c1a4c009b25ad5315c45ce51bc83983" alt="alert" width="10" height="10" data-path="images/gdk/reference/note.gif" /> **效能注意事項：**\
將項目加入佇列必須是無鎖定且無等候的，以符合上游程式碼的效能需求。下列 API 為無鎖定：

* [XTaskQueueSubmitCallback](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback)
* [XTaskQueueSubmitDelayedCallback](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitdelayedcallback)
* [XTaskQueueDispatch](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuedispatch)，前提是 *timeoutInMs* 傳遞 0

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

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

<Note>**SubmitCallback** 是在 [XTaskQueueSubmitCallback](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback) 函式的程式碼範例中定義的協助程式函式。</Note>

```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 主機

## 概念文件

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

## 另請參閱

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


## Related topics

- [XTaskQueueDispatch](/reference/system/xtaskqueue/functions/xtaskqueuedispatch.md)
- [XTaskQueueDispatchMode](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)