Documentation
¶
Overview ¶
Package match 提供有状态实时会话原语,采用 actor 模型: 每个会话(房间/对战/协作编辑)由独立 goroutine 驱动,固定帧率 tick, 所有输入(业务数据、成员变更、同步信号)经带缓冲 channel 串行消费, 状态封装在 goroutine 内,无需锁。
单 goroutine + ticker + 背压降级模式。 适用场景:游戏房间、权威对战、协作编辑、实时同步状态机等需要 "固定帧率 + 串行状态更新 + 慢消费降级"的长连接会话。
零值不可用,请用 New 构造。
Index ¶
- type Handler
- type Match
- func (m *Match[S, I, O]) QueueInput(in I) bool
- func (m *Match[S, I, O]) QueueJoin(p Presence) bool
- func (m *Match[S, I, O]) QueueLeave(p Presence) bool
- func (m *Match[S, I, O]) Rate() int
- func (m *Match[S, I, O]) Signal(fn func(S)) bool
- func (m *Match[S, I, O]) Start(ctx context.Context) error
- func (m *Match[S, I, O]) Stop()
- func (m *Match[S, I, O]) Stopped() bool
- func (m *Match[S, I, O]) Subscribe(ctx context.Context) (<-chan O, func())
- func (m *Match[S, I, O]) TickCount() int64
- func (m *Match[S, I, O]) Wait() error
- type Option
- type Presence
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Handler ¶
type Handler[S any, I any, O any] interface { // Init 初始化会话状态并返回期望的帧率(Hz,每秒 tick 次数)。 // rate<=0 时回退到 WithTickRate 设定值。params 由 New 透传。 Init(params map[string]any) (state S, rate int, err error) // Tick 在每个帧周期被调用,接收本帧累积的全部输入与成员变更, // 返回演进后的新状态与待广播的产出。返回 error 会终止会话。 Tick(ctx context.Context, state S, inputs []I, join []Presence, leave []Presence) (S, []O, error) }
Handler 由业务实现,定义会话的状态转移。 三个类型参数:
- S: 会话状态(如房间快照、棋盘),由 Init 创建、Tick 演进。
- I: 单条输入(如玩家操作),通过 QueueInput 投递。
- O: 单条产出(如广播消息),Tick 返回后扇出给所有订阅者。
type Match ¶
Match 是一个有状态实时会话实例。零值不可用,用 New 创建。
func New ¶
func New[S any, I any, O any](handler Handler[S, I, O], params map[string]any, opts ...Option) *Match[S, I, O]
New 创建一个会话实例。handler 由业务实现,params 透传给 Handler.Init。
m := match.New[State, Input, Msg](roomHandler{}, nil,
match.WithTickRate(20),
match.WithMaxIdleSec(30),
)
m.Start(ctx)
func (*Match[S, I, O]) QueueInput ¶
QueueInput 非阻塞投递一条输入。会话已停止或队列满时返回 false(丢弃)。 丢弃而非阻塞:慢消费不应拖垮生产端,背压策略。 输入在 inputCh 中累积,由下一次 tick 批量 drain 并交给 Handler.Tick。
func (*Match[S, I, O]) QueueLeave ¶
QueueLeave 非阻塞投递一个成员离开事件。队列满时丢弃。
func (*Match[S, I, O]) Signal ¶
Signal 投递一个同步调用,在 loop goroutine 内串行执行,可安全读取 state。 fn 收到的 S 即当前会话状态(只读快照)。会话已停止或过载时返回 false。 signal 与 tick 共享 callCh,队列满时视为过载,会停止会话。
func (*Match[S, I, O]) Start ¶
Start 启动会话 loop goroutine。多次调用幂等,仅首次生效。 返回 Init 的错误(若有)。ctx 取消时触发优雅停止。
func (*Match[S, I, O]) Stop ¶
func (m *Match[S, I, O]) Stop()
Stop 优雅停止会话:关闭订阅者,通知 loop 退出。幂等。 用 Wait() 等待 loop 完全退出。
func (*Match[S, I, O]) Subscribe ¶
Subscribe 注册一个订阅者,返回只读 channel 与取消函数。 Tick 返回的产出会扇出给所有订阅者;某订阅者队列满时按策略丢弃(默认丢最旧)。 ctx 取消或 Match.Stop 时自动注销并关闭 channel。
type Option ¶
type Option func(*config)
Option 配置 Match。
func WithCallQueue ¶
WithCallQueue 设置帧与信号的串行执行队列容量,默认 64。 队列满时视为 loop 过载,会停止会话以避免无限堆积。
func WithInputQueue ¶
WithInputQueue 设置输入队列容量,默认 128。队列满时 QueueInput 丢弃并返回 false。
func WithMaxIdleSec ¶
WithMaxIdleSec 设置空闲自动停止的秒数:连续 N 帧(=rate*sec)既无输入也无订阅者即停止。 默认 0 表示不自动停止。
func WithSubBufferSize ¶
WithSubBufferSize 设置每个订阅者 channel 容量,默认 64。
func WithSubDropOldest ¶
WithSubDropOldest 设置订阅者队列满时丢弃策略:true 丢最旧(默认),false 丢最新。
Source Files