非同步作業和通知

對於可能較慢或計算成本較高的作業，PlayFab Lobby 和 Matchmaking SDK 會公開非同步 API。非同步 API 讓您能夠從主執行緒啟動成本高或較慢的作業，並在您選擇的執行緒上輪詢這些作業是否完成。相同的輪詢機制也用於將 SDK 更新的非同步通知傳遞給您的遊戲程式碼。本頁面概述 PlayFab Lobby 和 Matchmaking SDK 的非同步 API 模式，以及針對這些模式進行程式設計的最佳做法。

基本 API 模式

在 PlayFab Lobby 和 Matchmaking SDK 中，需要注意兩種類型的非同步 API 模式：

非同步作業
非同步通知

非同步作業

使用 SDK 的非同步 API 很簡單。啟動和完成非同步作業的一般模式如下：

對您選擇的適當非同步 API 進行一般方法呼叫。您可能會使用的常見非同步作業包括：
使用 SUCCEEDED() 或 FAILED() 巨集檢查 API 的 HRESULT 傳回值。這個同步傳回的值會告訴您作業是否已成功啟動。

非同步 API 呼叫的同步傳回值不會告訴您作業是否已成功完成。如需同步與非同步錯誤的詳細資訊，請參閱 SDK 的錯誤處理文件。

尋找由 PFMultiplayerStartProcessingLobbyStateChanges() 或 PFMultiplayerStartProcessingMatchmakingStateChanges 提供的相關作業「完成狀態變更」，以輪詢非同步作業是否完成。PFMultiplayerCreateAndJoinLobby() 相關「完成狀態變更」的範例是 PFLobbyCreateAndJoinLobbyCompletedStateChange。如需「狀態變更」是什麼及其運作方式的更詳細資訊，請參閱狀態變更一節。
檢查完成狀態變更的 result 值，以判斷作業是成功還是失敗。如需這些錯誤值的更詳細資訊，請參閱 SDK 的錯誤處理文件。

非同步通知

某些功能會產生 Lobby 和 Matchmaking SDK 變更的非同步通知。常見的通知包括：

SDK 會透過 PFMultiplayerStartProcessingLobbyStateChanges() 和 PFMultiplayerStartProcessingMatchmakingStateChanges，以「狀態變更」的形式將這些非同步通知提供給您。如需「狀態變更」是什麼及其運作方式的更詳細資訊，請參閱狀態變更一節。

狀態變更

Lobby 和 Matchmaking SDK 的非同步 API 模型是圍繞 PFLobbyStateChange 和 PFMatchmakingStateChange 結構建置的。PFLobbyStateChanges 會通知您大廳子系統的變更，而 PFMatchmakingStateChanges 會通知您配對子系統的變更。這些「狀態變更」是來自 SDK 之事件的非同步通知。這些通知會在內部排入佇列，您可以呼叫 PFMultiplayerStartProcessingLobbyStateChanges() 和 PFMultiplayerStartProcessingMatchmakingStateChanges 來處理它們。這些函式會以清單形式傳回 (各自 API 子系統的) 所有已排入佇列的狀態變更，您可以逐一查看並個別處理。每個狀態變更都有對應的 stateChangeType 欄位，可以檢查該欄位以判斷您收到的是哪個特定狀態變更的通知。一旦您知道收到的是哪個狀態變更，就可以將一般的 PFLobbyStateChange 或 PFMatchmakingStateChange 結構轉換為更具體的狀態變更結構類型，以檢查該事件的特定資料。通常，狀態變更處理會實作為一個簡單的 switch 陳述式，將每個狀態變更委派給處理常式。處理完來自 PFMultiplayerStartProcessingLobbyStateChanges 或 PFMultiplayerStartProcessingMatchmakingStateChanges 的狀態變更清單後，必須分別將其傳回給 PFMultiplayerFinishProcessingMatchmakingStateChanges() 或 PFMultiplayerFinishProcessingMatchmakingStateChanges()。

//
// Process Lobby state changes
//
uint32_t lobbyStateChangeCount;
const PFLobbyStateChange * const * lobbyStateChanges;
HRESULT hr = PFMultiplayerStartProcessingLobbyStateChanges(m_pfmHandle, &lobbyStateChangeCount, &lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < lobbyStateChangeCount; ++i)
{
    const PFLobbyStateChange* stateChange = lobbyStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFLobbyStateChangeType::CreateAndJoinLobbyCompleted:
        {
            HandleCreateAndJoinLobbyCompleted(
                static_cast<const PFLobbyCreateAndJoinLobbyCompletedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingLobbyStateChanges(m_pfmHandle, lobbyStateChangeCount, lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

//
// Process Match state changes
//
uint32_t matchStateChangeCount;
const PFMatchmakingStateChange * const * matchStateChanges;
hr = PFMultiplayerStartProcessingMatchmakingStateChanges(m_pfmHandle, &matchStateChangeCount, &matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < matchStateChangeCount; ++i)
{
    const PFMatchmakingStateChange* stateChange = matchStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFMatchmakingStateChangeType::TicketStatusChanged:
        {
            HandleMatchmakingTicketStatusChanged(
                static_cast<const PFMatchmakingTicketStatusChangedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(m_pfmHandle, matchStateChangeCount, matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

非同步作業內容

每個非同步 API 都包含一個 void* asyncContext 參數。此值是一個傳遞參數，一旦 PFMultiplayerStartProcessingLobbyStateChanges() 或 PFMultiplayerStartProcessingMatchmakingStateChanges() 提供此 API 呼叫相關的完成狀態變更，就會在其上設定此值。此值為您提供一種機制，將任意的指標大小內容附加至您的非同步 API 呼叫。這些內容可用於許多情境，包括：

將遊戲專屬資料與 SDK 呼叫建立關聯
以共用識別碼將多個非同步作業連結在一起

使用 SDK 時不一定需要這些非同步內容，但它們可以讓某些遊戲邏輯更容易撰寫。

作業佇列

使用非同步 API 時，經常需要將多個非同步作業依序執行，作為更大的非同步流程的一部分。在 Lobby 和 Matchmaking SDK 中，其中一個例子是建立大廳並為該大廳傳送邀請給朋友。依序執行時，此流程看起來會像這樣：

呼叫 PFMultiplayerCreateAndJoinLobby() 以建立並加入 PlayFab 大廳。
等候 PFLobbyCreateAndJoinLobbyCompletedStateChange 反映大廳已成功建立並加入。
為每位受邀的朋友呼叫 PFLobbySendInvite()。
等候 PFLobbySendInviteCompletedStateChange 反映邀請已成功傳送。

對於更複雜的流程和遊戲邏輯，這種依序執行的模式可能較為適當。不過，對於較簡單的流程，SDK 提供了一個旨在簡化遊戲程式碼的替代方案： SDK 中的許多非同步 API 都支援在先前的作業完全完成之前將相依作業排入佇列。以先前的範例來說，您可以在看到大廳成功建立之前就傳送該大廳的邀請。實際上，佇列可讓您將一組非同步作業組合在一起、一次全部啟動，並將錯誤處理合併到單一失敗點。

PFLobbyHandle newLobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobby(m_pfmHandle, myPlayerEntityId, newLobbyConfiguration, nullptr, nullptr, &newLobby);
if (SUCCEEDED(hr))
{
    for (size_t i = 0; SUCCEEDED(hr) && i < friends.size(); ++i)
    {
        hr = PFLobbySendInvite(m_pfmHandle, myPlayerEntityId, friends[i], nullptr);
    }

    if (SUCCEEDED(hr))
    {
        m_lobby = newLobby;
        Log("Created lobby and invited %zu friends!", friends.size());
    }
    else
    {
        // For the purposes of demonstration, we could have a policy that we shouldn't bother with any lobbies where
        // we couldn't invite all of our friends.
        (void) PFLobbyLeave(newLobby, myPlayerEntityId, nullptr);
    }
}

控制非同步工作

遊戲有時需要控制非同步工作的執行位置，以避免程式庫與遊戲核心 CPU 工作負載之間的 CPU 競爭。 Lobby 和 Matchmaking SDK 可讓您透過控制執行緒親和性來控制非同步工作的執行方式

控制執行緒親和性

根據預設，非同步 SDK 工作是在受到嚴格控制的背景執行緒上完成的。某些遊戲需要對這些背景執行緒的排程位置進行粗略的控制，以避免 CPU 競爭。對於這些遊戲，Lobby 和 Matchmaking SDK 提供了 PFMultiplayerSetThreadAffinityMask()。在支援的平台上，這可讓您限制 SDK 背景執行緒將使用哪些 CPU 核心。如此一來，您就可以保證保留某些核心給您自己的 CPU 工作負載，而不會發生任何競爭。

XBOX Services

PlayFab

非同步 Lobby 和 Matchmaking C++ SDK 作業指南

非同步作業和通知

基本 API 模式

非同步作業

非同步通知

狀態變更

非同步作業內容

作業佇列

控制非同步工作

控制執行緒親和性

​非同步作業和通知

​基本 API 模式

​非同步作業

​非同步通知

​狀態變更

​非同步作業內容

​作業佇列

​控制非同步工作

​控制執行緒親和性

非同步作業和通知

基本 API 模式

非同步作業

非同步通知

狀態變更

非同步作業內容

作業佇列

控制非同步工作

控制執行緒親和性