12.1 回调机制
前面每一章都在用回调(ValidateAuthTicketResponse_t、GSStatsReceived_t、GlobalStatsReceived_t……),这一节把它们背后的机制讲透:Steamworks 的事件模型是回调驱动——Steam 客户端把事件排队,游戏在自己的循环里调 SteamAPI_RunCallbacks() 把它们泵出来分发给监听者。接入工程要理解注册/注销、派发时机、两套队列(客户端 vs 游戏服务器)与手动分发模式。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/steam_api_common.h、steam_api_internal.h、steam_api.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台配置事件订阅」;本节讲「回调在游戏循环里怎么被分发」。
- 卷一《平台机制与商店》讲平台机制;本节把「事件」落成回调注册与派发的工程口径。
- lab 用纯 C++ 复现回调注册/注销、FIFO 派发与队列分离,不依赖 Steam 客户端运行。
回调的消息结构:CallbackMsg_t
Steam 把待分发的事件封装成一个消息结构。SDK v1.65 的 CallbackMsg_t:
// steam_api_internal.h:CallbackMsg_t(SDK v1.65 头文件摘录,已删减)
struct CallbackMsg_t
{
HSteamUser m_hSteamUser; // Specific user to whom this callback applies.
int m_iCallback; // Callback identifier. (Corresponds to the k_iCallback enum in the callback structure.)
uint8 *m_pubParam; // Points to the callback structure
int m_cubParam; // Size of the data pointed to by m_pubParam
};
工程语义:
m_iCallback是回调 id,即回调结构里的k_iCallback:每个回调结构体用enum { k_iCallback = <base> + <offset> }声明自己的唯一 id。id 的基址按接口域分区(k_iSteamUserCallbacks = 100、k_iSteamGameServerCallbacks = 200、k_iSteamFriendsCallbacks = 300、k_iSteamAppsCallbacks = 1000、k_iSteamUserStatsCallbacks = 1100……)——这是回调 id 永远唯一的机制保证。m_pubParam/m_cubParam是指向回调结构的指针与大小:分发器按m_iCallback找监听,把m_pubParam强转成对应结构体类型交给处理函数。id 一旦注册错位,强转就错——所以回调 id 的一致性检查是必要的。m_hSteamUser标记回调归属的用户:多用户管道(steam pipe)场景下,不同用户的回调由不同句柄区分。工程上处理多用户时不能只看回调内容,还要看归属句柄。
注册与注销:监听的生命周期
监听器用 CCallbackBase 派生对象向 Steam 登记:
// steam_api_internal.h:回调注册(SDK v1.65 头文件摘录,已删减)
S_API void S_CALLTYPE SteamAPI_RegisterCallback( class CCallbackBase *pCallback, int iCallback );
S_API void S_CALLTYPE SteamAPI_UnregisterCallback( class CCallbackBase *pCallback );
工程语义:
- 注册发生在对象构造时,注销在析构时:
STEAM_CALLBACK宏声明的成员变量在构造时自动SteamAPI_RegisterCallback、析构时自动注销。用STEAM_CALLBACK_MANUAL则要自己调Register/Unregister。工程上若手动管理,注销必须与注册对称,否则析构后回调仍会派发进已死对象。 - 同一回调 id 可以有多个监听器:一个事件通知多份逻辑(UI 更新 + 数据落盘 + 埋点)是常见用法。注册是追加式,不是覆盖式。
- 注销按对象、不按 id:
SteamAPI_UnregisterCallback收的是监听器对象指针,事件到来时不再派发给它。注销一个回调 id 的全部监听器,要么逐个注销对象,要么(工程侧)自己维护注册表。
派发:RunCallbacks 与两套队列
排队的事件不会自动到达——游戏必须在自己的主循环里主动泵取。SDK v1.65 的入口:
// steam_api_common.h:回调泵(SDK v1.65 头文件摘录,已删减)
// Dispatch all queued Steamworks callbacks.
// This is safe to call from multiple threads simultaneously,
// but if you choose to do this, callback code could be executed on any thread.
S_API void S_CALLTYPE SteamAPI_RunCallbacks();
// Dispatch callbacks relevant to the gameserver client and interfaces.
// To register for these, you need to use STEAM_GAMESERVER_CALLBACK.
S_API void S_CALLTYPE SteamGameServer_RunCallbacks();
工程语义:
SteamAPI_RunCallbacks()是客户端事件泵,SteamGameServer_RunCallbacks()是游戏服务器事件泵:两套队列按回调的注册来源分拣——普通回调走前者,STEAM_GAMESERVER_CALLBACK注册的走后者。游戏服务器进程要同时泵两套,别只泵一套导致事件滞留。- 泵的时机在主循环里,频率自己定:注释明说它可以从多线程同时调,但那样回调可能在任何线程执行。工程上默认「主线程定时泵」,工作线程要做内存清理就调
SteamAPI_ReleaseCurrentThreadMemory。 - 泵是 FIFO 的:先排队的事件先分发。依赖事件顺序的逻辑(比如「连接成功」必须在「认证结果」之前)能成立,前提是同一管道内的 FIFO 不被破坏。
- 泵是拉模型,不是推模型:事件在 Steam 客户端里排队,直到游戏调
RunCallbacks才被取出分发。游戏阻塞太久(比如每帧只泵一次、帧又很长)会延迟事件到达——工程上对时间敏感的回调要保证泵的频度。
手动分发模式
对「不用 SteamAPI_RunCallbacks、自己控制回调循环」的集成(比如嵌入非游戏主循环),SDK 提供手动分发:
// steam_api.h:手动分发(SDK v1.65 头文件摘录,已删减)
S_API void S_CALLTYPE SteamAPI_ManualDispatch_RunFrame( HSteamPipe hSteamPipe );
S_API bool S_CALLTYPE SteamAPI_ManualDispatch_GetNextCallback( HSteamPipe hSteamPipe, CallbackMsg_t *pCallbackMsg );
S_API void S_CALLTYPE SteamAPI_ManualDispatch_FreeLastCallback( HSteamPipe hSteamPipe );
工程语义:
- 手动分发 = RunFrame + 逐个 GetNextCallback 取:每次循环推进管道帧,然后循环取回调处理。文档模板在
steam_api.h里示范了完整循环:RunFrame→while GetNextCallback→ 按callback.m_iCallback分发 →FreeLastCallback。 FreeLastCallback必须成对调用:取到一个回调处理完,必须先FreeLastCallback才能取下一个——文档注释强调这一点。漏掉会导致回调累积、内存泄漏。- 手动模式与自动泵互斥:同一管道不能同时用
SteamAPI_RunCallbacks和手动分发。工程上要在初始化时选一条路走到底,混用会重复分发或漏分发。下面 lab 用manualMode_开关复现这个互斥。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
steam_api_internal.h | CallbackMsg_t | 排队回调的消息结构(id/参数/归属用户) |
steam_api_internal.h | SteamAPI_RegisterCallback | 注册监听(对象构造时自动) |
steam_api_internal.h | SteamAPI_UnregisterCallback | 注销监听(对象析构时自动) |
steam_api_common.h | SteamAPI_RunCallbacks | 客户端事件泵(FIFO,主循环调用) |
steam_api_common.h | SteamGameServer_RunCallbacks | 游戏服务器事件泵 |
steam_api.h | SteamAPI_ManualDispatch_* | 手动分发模式(RunFrame/GetNextCallback/FreeLastCallback) |
steam_api_internal.h | 回调基址常量 | k_iSteamUserCallbacks=100 / GameServer=200 / Friends=300 / Apps=1000 / UserStats=1100 |
数据口径与来源
CallbackMsg_t字段、注册/注销签名、泵签名、手动分发签名、回调基址常量:SDK v1.65public/steam/steam_api_common.h、steam_api_internal.h、steam_api.h可实证(本机镜像已核对)。- 「同一回调可多监听」「泵是多线程安全但回调可能跑在任意线程」「FreeLastCallback 必须成对」:头文件注释明文。
- 回调的实际触发频率、泵的推荐频度:工程经验口径,官方不约束,以自身性能预算为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「回调机制」的工程语义:按 callback id 注册/注销监听、同一回调多监听、FIFO 派发、客户端与游戏服务器两套队列独立泵取、手动分发模式禁用自动泵。它与 src/12-1-callback-mechanics.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/12-1-callback-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/12-1-callback-mechanics.cpp -o bin/12-1-callback-mechanics && ./bin/12-1-callback-mechanics
//
// mock:复现回调机制——按 callback id 注册/注销监听、FIFO 派发、
// 客户端与游戏服务器两套队列(RunCallbacks / SteamGameServer_RunCallbacks)、
// 手动分发互斥、析构自动注销。
// 签名对照 SDK v1.65 steam_api_common.h / steam_api_internal.h,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <functional>
#include <string>
#include <unordered_map>
#include <vector>
namespace steam_repro {
// CallbackMsg_t 语义:回调标识 + 参数指针 + 参数长度(steam_api_internal.h)
struct MockCallbackMsg {
int callbackId;
std::string payload;
bool gameServer;
};
class MockCallbackSystem {
public:
using Handler = std::function<void(const std::string&)>;
// SteamAPI_RegisterCallback:同一回调允许多个监听
void registerCallback(int cb, Handler h) { handlers_[cb].push_back(std::move(h)); }
// SteamAPI_UnregisterCallback:按「回调 id」注销全部监听
void unregisterAll(int cb) { handlers_.erase(cb); }
// 入队一个回调事件(客户端或游戏服务器管道的消息)
void enqueue(int cb, const std::string& payload, bool gameServer) {
queued_.push_back({cb, payload, gameServer});
}
// SteamAPI_RunCallbacks:泵出所有客户端回调;手动分发模式下禁用
size_t runCallbacks() {
if (manualMode_) return 0;
return dispatchQueue(false);
}
// SteamGameServer_RunCallbacks:泵出游戏服务器回调
size_t runGameServerCallbacks() { return dispatchQueue(true); }
void enableManualDispatch() { manualMode_ = true; }
size_t delivered() const { return delivered_; }
size_t pendingCount() const { return queued_.size(); }
private:
size_t dispatchQueue(bool gs) {
size_t n = 0;
size_t i = 0;
while (i < queued_.size()) {
const MockCallbackMsg& msg = queued_[i];
if (msg.gameServer != gs) {
++i;
continue;
}
auto it = handlers_.find(msg.callbackId);
if (it != handlers_.end()) {
for (const auto& h : it->second) {
h(msg.payload);
++delivered_;
}
++n;
}
queued_.erase(queued_.begin() + static_cast<long>(i));
}
return n;
}
bool manualMode_ = false;
size_t delivered_ = 0;
std::unordered_map<int, std::vector<Handler>> handlers_;
std::vector<MockCallbackMsg> queued_;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockCallbackSystem sys;
int hits[3] = {0, 0, 0};
// 1. 注册两个回调监听
sys.registerCallback(1001, [&](const std::string&) { ++hits[0]; });
sys.registerCallback(1002, [&](const std::string& s) { hits[1] += static_cast<int>(s.size()); });
// 2. 同一回调注册第二个监听器
sys.registerCallback(1001, [&](const std::string&) { ++hits[2]; });
// 3. 空队列 pump 无派发
CHECK(sys.runCallbacks() == 0);
CHECK(sys.delivered() == 0);
// 4. 入队并 pump:FIFO 派发
sys.enqueue(1001, "evt1", false);
sys.enqueue(1002, "abc", false);
CHECK(sys.runCallbacks() == 2);
CHECK(hits[0] == 1);
CHECK(hits[1] == 3);
CHECK(hits[2] == 1);
// 5. 注销 1001 后不再派发
sys.unregisterAll(1001);
sys.enqueue(1001, "again", false);
sys.enqueue(1002, "x", false);
CHECK(sys.runCallbacks() == 1); // 只有 1002 派发
CHECK(hits[0] == 1);
CHECK(hits[2] == 1);
// 6. 手动分发模式禁用自动 pump
MockCallbackSystem manual;
manual.enableManualDispatch();
manual.registerCallback(2001, [&](const std::string&) { ++hits[0]; });
manual.enqueue(2001, "m", false);
CHECK(manual.runCallbacks() == 0);
// 7. 游戏服务器回调独立泵
MockCallbackSystem gs;
gs.registerCallback(2010, [&](const std::string&) { ++hits[0]; });
gs.enqueue(2010, "gs", true);
CHECK(gs.runGameServerCallbacks() == 1);
CHECK(gs.runCallbacks() == 0); // 队列已清空
// 8. 客户端系统累计派发次数
CHECK(sys.delivered() == 4);
return lab::report("12-1 回调机制");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 13/13 通过。
小结
- Steamworks 是回调驱动:事件排队,
SteamAPI_RunCallbacks()泵出分发;回调 id 按接口域分区保证唯一。 - 注册/注销随监听对象构造/析构自动进行,同一回调 id 可有多监听,注销按对象不按 id。
- 客户端与游戏服务器是两套队列,分别由
SteamAPI_RunCallbacks与SteamGameServer_RunCallbacks泵取。 - 手动分发模式(RunFrame + GetNextCallback + FreeLastCallback)与自动泵互斥,不能混用。
阅读导航:上一节:11.3 测试策略与数据 · 下一节:12.2 异步操作模式 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。