《Steam 游戏平台:开发与商业化》12.2 异步操作模式

SteamAPICall_t 句柄驱动异步:发起返回句柄,IsAPICallCompleted 查询完成态,GetAPICallResult 取结果,GetAPICallFailureReason 解释失败。本节讲句柄生命周期、失败分支与 CCallResult 自动交付的工程语义,lab 用 C++ mock 验证句柄/失败/CCallResult 生命周期。

12.2 异步操作模式

上一节讲了回调机制,这一节讲另一种事件形态:异步操作(API call)。很多 Steam 接口(RequestUserStats、RequestGlobalStats、RequestAuthTicket……)不直接返回结果,而是返回一个 SteamAPICall_t 句柄,结果稍后通过回调或轮询取回。接入工程要掌握句柄的完整生命周期:发起 → 查询完成 → 取结果/读失败原因 → 完成或放弃。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamutils.h、steam_api_common.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台配置各类异步数据」;本节讲「异步句柄在代码里怎么被正确消费」。
  • 卷一《平台机制与商店》讲平台机制;本节把「异步结果」落成句柄/失败分支/自动交付的工程口径。
  • lab 用纯 C++ 复现句柄与 CCallResult 生命周期,不依赖 Steam 客户端运行。

异步句柄:SteamAPICall_t 的生命周期

一个异步操作从「发起接口返回句柄」开始。查询接口在 ISteamUtils 上:

// isteamutils.h:ISteamUtils 异步查询(SDK v1.65 头文件摘录,已删减)
virtual bool IsAPICallCompleted( SteamAPICall_t hSteamAPICall, bool *pbFailed ) = 0;
virtual ESteamAPICallFailure GetAPICallFailureReason( SteamAPICall_t hSteamAPICall ) = 0;
virtual bool GetAPICallResult( SteamAPICall_t hSteamAPICall, void *pCallback, int cubCallback, int iCallbackExpected, bool *pbFailed ) = 0;

工程语义:

  1. 句柄生命周期分三态:pending(未完成)→ completed(成功)→ failed(失败)。IsAPICallCompleted 返回完成与否,同时用 pbFailed 指出是否失败。工程上要同时读两个输出,不能只看返回值。
  2. GetAPICallResult 要求回调类型匹配:iCallbackExpected 是你期望的回调 id,与句柄实际携带的不一致就失败(k_ESteamAPICallFailureMismatchedCallback)。工程上取结果必须传「发起接口声明的回调类型」,否则静默失败。
  3. 缓冲区太小也会失败:cubCallback 小于实际结果尺寸时取回失败。先查大小再取数据,或一次给够,是接入惯例。
  4. GetAPICallFailureReason 解释失败:v1.65 的枚举把失败分成四类——Steam 进程消失(SteamGone)、网络断开(NetworkFailure)、句柄已不存在(InvalidHandle)、回调类型不匹配(MismatchedCallback)。工程上要按类分别处理:SteamGone 提示重启客户端,NetworkFailure 等网络恢复重试,InvalidHandle 说明句柄已过期,MismatchedCallback 是代码 bug。

失败分支:ESteamAPICallFailure

失败枚举的具体值与语义:

// isteamutils.h:ESteamAPICallFailure(SDK v1.65 头文件摘录,已删减)
enum ESteamAPICallFailure
{
	k_ESteamAPICallFailureNone = -1,			// no failure
	k_ESteamAPICallFailureSteamGone = 0,		// the local Steam process has gone away
	k_ESteamAPICallFailureNetworkFailure = 1,	// the network connection to Steam has been broken, or was already broken
	k_ESteamAPICallFailureInvalidHandle = 2,	// the SteamAPICall_t handle passed in no longer exists
	k_ESteamAPICallFailureMismatchedCallback = 3,// GetAPICallResult() was called with the wrong callback type for this API call
};

工程语义:

  1. None = -1 表示没有失败:查询一个成功完成的句柄,GetAPICallFailureReason 返回 k_ESteamAPICallFailureNone。工程上不要在成功路径里把 None 当错误处理。
  2. InvalidHandle 是「句柄已不存在」,不是「操作失败」:句柄过期、被清理、或本身是伪造值都会落到它。工程上区别对待:操作失败有业务原因,InvalidHandle 多半是句柄生命周期管理问题。
  3. 失败处理要落在正确层级:SteamGone/NetworkFailure 是「平台不可用」,重试没有意义直到平台恢复;InvalidHandle/MismatchedCallback 是「调用方问题」,重试也没用但要修代码。工程上不要把所有失败都当「重试一次就行」。

CCallResult:把轮询变成自动交付

对「发起 → 等结果 → 交付」这种模式,SDK 提供 CCallResult 模板,把句柄与成员函数绑定,完成后自动调用:

// steam_api_common.h:CCallResult(SDK v1.65 头文件摘录,已删减)
// CCallResult is used with specific Steam APIs that return "result handles".
// The handle can be passed to a CCallResult object's Set function, along with a function pointer.
class CCallResult : private CCallbackBase
{
	void Set( SteamAPICall_t hAPICall, T *p, func_t func );
	bool IsActive() const;
	void Cancel();
};

工程语义:

  1. Set(hAPICall, obj, func) 绑定句柄与处理函数:结果完成时 SDK 自动调用 func,把结果结构体交给它。这消除了手动轮询 IsAPICallCompleted/GetAPICallResult 的样板代码。
  2. IsActive() 表示该句柄是否还在等待交付:句柄已完成、已交付、或被取消,都返回 false。工程上用它在析构前检查是否有未完成的异步回调。
  3. Cancel() 放弃等待:取消后即使结果到达也不会再调用 func。对象析构前必须 Cancel,否则回调可能派发进已析构对象——这与上一节的注销对称原则一致。
  4. 一次 Set 对应一次交付:交付完成(deliver)后 IsActive 转 false,同一个 CCallResult 对象可以 Set 新句柄复用于下一次异步操作。

接口签名对照

头文件条目语义
isteamutils.hISteamUtils::IsAPICallCompleted查询句柄是否完成(含失败标记输出)
isteamutils.hISteamUtils::GetAPICallFailureReason读失败原因枚举
isteamutils.hISteamUtils::GetAPICallResult取结果(要求回调类型与缓冲区匹配)
isteamutils.hESteamAPICallFailure失败分类(SteamGone/Network/InvalidHandle/MismatchedCallback)
steam_api_common.hCCallResult句柄自动交付模板(Set/IsActive/Cancel)

数据口径与来源

  • IsAPICallCompleted/GetAPICallFailureReason/GetAPICallResult 签名与 ESteamAPICallFailure 各值注释:SDK v1.65 public/steam/isteamutils.h 可实证(本机镜像已核对)。
  • CCallResult 的 Set/IsActive/Cancel 与「结果句柄」注释:SDK v1.65 public/steam/steam_api_common.h 可实证(本机镜像已核对)。
  • 各异步接口的失败重试策略:工程经验口径,官方不约束具体策略,以自身业务语义为准。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「异步操作模式」的工程语义:SteamAPICall_t 句柄的 pending/completed/failed 三态、IsAPICallCompleted 与失败标记、回调类型不匹配失败、GetAPICallFailureReason 分支、CCallResult 的 Set/IsActive/deliver/Cancel 生命周期。它与 src/12-2-async-operation.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/12-2-async-operation.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/12-2-async-operation.cpp -o bin/12-2-async-operation && ./bin/12-2-async-operation
//
// mock:复现异步操作模式——SteamAPICall_t 句柄、IsAPICallCompleted /
// GetAPICallResult / GetAPICallFailureReason、ESteamAPICallFailure 分支,
// 以及 CCallResult 的 Set/IsActive/Cancel 生命周期。
// 签名对照 SDK v1.65 isteamutils.h / steam_api_common.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <functional>
#include <string>
#include <unordered_map>
#include <unordered_set>

namespace steam_repro {

// ESteamAPICallFailure 枚举值对照 isteamutils.h
enum MockCallFailure {
  kNone = -1,
  kSteamGone = 0,
  kNetworkFailure = 1,
  kInvalidHandle = 2,
  kMismatchedCallback = 3,
};

struct MockAsyncResult {
  uint64_t handle;
  int callbackId;
  std::string bytes;
  bool failed;
  MockCallFailure failure;
};

// UserStatsReceived_t 回调结构字段对照 isteamuserstats.h
struct MockUserStatsReceived {
  enum { kCallback = 1100 + 1 };
  uint64_t gameId;
  int result;
  uint64_t steamIdUser;
};

class MockAsyncSystem {
 public:
  // 发起一个异步调用(返回 SteamAPICall_t)
  uint64_t start(int callbackId, const std::string& bytes) {
    uint64_t h = nextHandle_++;
    results_[h] = MockAsyncResult{h, callbackId, bytes, false, kNone};
    pending_.insert(h);
    return h;
  }

  // 推进:完成所有 pending
  void pump() {
    for (uint64_t h : pending_) {
      auto it = results_.find(h);
      if (it != results_.end()) it->second.failed = false;
    }
    pending_.clear();
  }

  // 标记失败
  void fail(uint64_t h, MockCallFailure why) {
    auto it = results_.find(h);
    if (it == results_.end()) return;
    it->second.failed = true;
    it->second.failure = why;
    pending_.erase(h);
  }

  // ISteamUtils::IsAPICallCompleted
  bool isAPICallCompleted(uint64_t h, bool* pbFailed) const {
    auto it = results_.find(h);
    if (it == results_.end()) {
      if (pbFailed) *pbFailed = true;
      return true;
    }
    bool complete = pending_.count(h) == 0;
    if (pbFailed) *pbFailed = it->second.failed;
    return complete;
  }

  // ISteamUtils::GetAPICallFailureReason
  MockCallFailure getAPICallFailureReason(uint64_t h) const {
    auto it = results_.find(h);
    if (it == results_.end()) return kInvalidHandle;
    return it->second.failed ? it->second.failure : kNone;
  }

  // ISteamUtils::GetAPICallResult
  bool getAPICallResult(uint64_t h, void* out, int cub, int expectedCallback,
                        bool* pbFailed) const {
    auto it = results_.find(h);
    if (it == results_.end()) return false;
    const MockAsyncResult& r = it->second;
    if (r.callbackId != expectedCallback) {
      if (pbFailed) *pbFailed = true;
      return false;
    }
    if (cub < static_cast<int>(r.bytes.size())) return false;
    if (out) {
      for (size_t i = 0; i < r.bytes.size(); ++i)
        static_cast<char*>(out)[i] = r.bytes[i];
    }
    if (pbFailed) *pbFailed = r.failed;
    return true;
  }

  size_t pendingCount() const { return pending_.size(); }

 private:
  uint64_t nextHandle_ = 1;
  std::unordered_map<uint64_t, MockAsyncResult> results_;
  std::unordered_set<uint64_t> pending_;
};

// CCallResult 简化版:绑定句柄 + 回调
class MockCallResult {
 public:
  using Handler = std::function<void(const std::string&, bool)>;

  void set(uint64_t h, Handler f) {
    handle_ = h;
    handler_ = std::move(f);
    active_ = h != 0;
  }
  bool isActive() const { return active_; }
  void cancel() {
    active_ = false;
    handle_ = 0;
  }
  void deliver(const std::string& bytes, bool failed) {
    if (active_ && handler_) handler_(bytes, failed);
    active_ = false;
  }
  uint64_t handle() const { return handle_; }

 private:
  uint64_t handle_ = 0;
  bool active_ = false;
  Handler handler_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockAsyncSystem sys;

  // 1. 未知句柄 → 已完成且失败
  bool failed = false;
  CHECK(sys.isAPICallCompleted(999, &failed));
  CHECK(failed);

  // 2. 发起异步调用:pending 未完成
  uint64_t h = sys.start(MockUserStatsReceived::kCallback, "abc");
  CHECK(!sys.isAPICallCompleted(h, &failed));
  CHECK(sys.pendingCount() == 1);

  // 3. 结果就绪后可取回
  sys.pump();
  CHECK(sys.isAPICallCompleted(h, &failed));
  CHECK(!failed);

  // 4. 正确回调 id 取结果
  char out[8] = {0};
  bool f = true;
  CHECK(sys.getAPICallResult(h, out, 3, MockUserStatsReceived::kCallback, &f));
  CHECK(f == false);
  CHECK(std::string(out, 3) == "abc");

  // 5. 回调 id 不匹配 → 失败
  CHECK(!sys.getAPICallResult(h, out, 3, 999, &f));
  CHECK(f);

  // 6. 失败句柄的 failure reason
  uint64_t h2 = sys.start(MockUserStatsReceived::kCallback, "x");
  sys.fail(h2, kNetworkFailure);
  CHECK(sys.isAPICallCompleted(h2, &failed));
  CHECK(failed);
  CHECK(sys.getAPICallFailureReason(h2) == kNetworkFailure);

  // 7. 未知句柄 failure reason = InvalidHandle
  CHECK(sys.getAPICallFailureReason(12345) == kInvalidHandle);

  // 8. CCallResult:Set 后 IsActive
  MockCallResult cr;
  int calls = 0;
  cr.set(h, [&](const std::string&, bool) { ++calls; });
  CHECK(cr.isActive());
  CHECK(cr.handle() == h);

  // 9. deliver 调用绑定成员并清除 active
  cr.deliver("ok", false);
  CHECK(calls == 1);
  CHECK(!cr.isActive());

  // 10. cancel 后不再交付
  MockCallResult cr2;
  uint64_t h3 = sys.start(MockUserStatsReceived::kCallback, "z");
  cr2.set(h3, [&](const std::string&, bool) { ++calls; });
  cr2.cancel();
  CHECK(!cr2.isActive());
  cr2.deliver("should-not-call", false);
  CHECK(calls == 1);

  return lab::report("12-2 异步操作模式");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 21/21 通过。

小结

  • 异步操作以 SteamAPICall_t 句柄为凭:发起返回句柄,IsAPICallCompleted 查完成态,GetAPICallResult 取结果,GetAPICallFailureReason 解释失败。
  • 取结果要求回调类型匹配且缓冲区够大,否则静默失败;失败分支要按「平台不可用 / 调用方问题」分别处理。
  • CCallResult 把轮询变成自动交付:Set 绑定句柄与处理函数,完成后自动调用;IsActive 标记等待态,Cancel 放弃等待。
  • 对象析构前必须 Cancel 或等交付完成,避免回调派发进已析构对象。

阅读导航:上一节:12.1 回调机制 · 下一节:12.3 平台事件的产品设计 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图