异步操作与通知

对于可能较慢或计算量大的操作,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 结构构建的。PFLobbyStateChange 通知你关于大厅子系统的变更,PFMatchmakingStateChange 通知你关于匹配子系统的变更。这些 “状态变更” 是来自 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 模式

异步操作

异步通知

状态变更

异步操作上下文

操作排队

控制异步工作

控制线程亲和性