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;
工程语义:
- 句柄生命周期分三态:pending(未完成)→ completed(成功)→ failed(失败)。
IsAPICallCompleted返回完成与否,同时用pbFailed指出是否失败。工程上要同时读两个输出,不能只看返回值。 GetAPICallResult要求回调类型匹配:iCallbackExpected是你期望的回调 id,与句柄实际携带的不一致就失败(k_ESteamAPICallFailureMismatchedCallback)。工程上取结果必须传「发起接口声明的回调类型」,否则静默失败。- 缓冲区太小也会失败:
cubCallback小于实际结果尺寸时取回失败。先查大小再取数据,或一次给够,是接入惯例。 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
};
工程语义:
None = -1表示没有失败:查询一个成功完成的句柄,GetAPICallFailureReason返回k_ESteamAPICallFailureNone。工程上不要在成功路径里把None当错误处理。InvalidHandle是「句柄已不存在」,不是「操作失败」:句柄过期、被清理、或本身是伪造值都会落到它。工程上区别对待:操作失败有业务原因,InvalidHandle 多半是句柄生命周期管理问题。- 失败处理要落在正确层级: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();
};
工程语义:
Set(hAPICall, obj, func)绑定句柄与处理函数:结果完成时 SDK 自动调用func,把结果结构体交给它。这消除了手动轮询IsAPICallCompleted/GetAPICallResult的样板代码。IsActive()表示该句柄是否还在等待交付:句柄已完成、已交付、或被取消,都返回 false。工程上用它在析构前检查是否有未完成的异步回调。Cancel()放弃等待:取消后即使结果到达也不会再调用func。对象析构前必须 Cancel,否则回调可能派发进已析构对象——这与上一节的注销对称原则一致。- 一次 Set 对应一次交付:交付完成(
deliver)后IsActive转 false,同一个CCallResult对象可以Set新句柄复用于下一次异步操作。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamutils.h | ISteamUtils::IsAPICallCompleted | 查询句柄是否完成(含失败标记输出) |
isteamutils.h | ISteamUtils::GetAPICallFailureReason | 读失败原因枚举 |
isteamutils.h | ISteamUtils::GetAPICallResult | 取结果(要求回调类型与缓冲区匹配) |
isteamutils.h | ESteamAPICallFailure | 失败分类(SteamGone/Network/InvalidHandle/MismatchedCallback) |
steam_api_common.h | CCallResult | 句柄自动交付模板(Set/IsActive/Cancel) |
数据口径与来源
IsAPICallCompleted/GetAPICallFailureReason/GetAPICallResult签名与ESteamAPICallFailure各值注释:SDK v1.65public/steam/isteamutils.h可实证(本机镜像已核对)。CCallResult的 Set/IsActive/Cancel 与「结果句柄」注释:SDK v1.65public/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 平台事件的产品设计 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。