versus

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 8, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package versus 提供"限时多方对抗计分"原语:N 个阵营在一段倒计时内实时累计分, 到点定胜负。直播 PK、团战、答题赛、拉票等"双方/多方限时比拼"场景的通用抽象。

这是一个组合型原语,复用 beauty 已有的基础件:

  • pkg/fsm:对局状态机(pending→running→ended),非法操作(如结束后再加分)被拒;
  • pkg/stream:分数变化 / 开始 / 结束事件 fan-out 给订阅者(推给客户端渲染);
  • 内建单次倒计时(time.AfterFunc):到点自动结算。单对局自带定时器比共享 delayqueue 更自洽(无需外部生命周期);批量对局可在上层用 delayqueue 统管。

语义:

  • New 定义阵营与时长,初始 pending;Start 进入 running 并启动倒计时;
  • running 态 Add(side, delta) 累加分并广播 ScoreChanged;pending/ended 态 Add 报错;
  • 倒计时到点(或手动 Finish)进入 ended:计算领先方 / 平局,触发 OnEnd 回调 + 广播 Ended 事件。ended 是终态,幂等(重复 Finish 无副作用)。

并发安全。零值不可用,用 New 构造。对局结束或不再使用时调用 Close 释放资源。

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotRunning = errors.New("versus: match not running")

ErrNotRunning 对局不在进行中(pending 未开始 / ended 已结束),不能加分。

View Source 
var ErrUnknownSide = errors.New("versus: unknown side")

ErrUnknownSide 传入的阵营不在 New 声明的阵营列表中。

Functions

This section is empty.

Types

type Event 

type Event struct {
	Type EventType
	// Side 仅 EventScoreChanged 有意义:发生变化的阵营。
	Side string
	// Delta 仅 EventScoreChanged 有意义:本次变化量。
	Delta int64
	// Snapshot 事件发生后的对局快照。
	Snapshot Snapshot
}

Event 广播给订阅者的对局事件。

type EventType 

type EventType int

EventType 对外广播的事件类型。 

const (
	// EventStarted 对局开始。
	EventStarted EventType = iota
	// EventScoreChanged 某方分数变化。
	EventScoreChanged
	// EventEnded 对局结束(带最终结果)。
	EventEnded
)

func (EventType) String 

func (e EventType) String() string

type Match 

type Match struct {
	// contains filtered or unexported fields
}

Match 一场限时多方对抗。零值不可用,用 New 构造。并发安全。

func New 

func New(id string, sides []string, opts ...Option) *Match

New 创建一场对局。id 为对局标识,sides 为参与阵营(至少 1 个,通常 2 个)。

func (*Match) Add 

func (m *Match) Add(side string, delta int64) (int64, error)

Add 给 side 累加 delta(可为负,如撤回礼物),返回该 side 的新分数。 仅 running 态可加;非 running 返回 ErrNotRunning;未知 side 返回 ErrUnknownSide。

func (*Match) Close 

func (m *Match) Close()

Close 释放对局资源(停表、关闭事件广播)。幂等。

func (*Match) Finish 

func (m *Match) Finish()

Finish 手动提前结束对局(到点会自动结束,无需手动调用)。幂等。

func (*Match) Snapshot 

func (m *Match) Snapshot() Snapshot

Snapshot 返回当前对局快照。

func (*Match) Start 

func (m *Match) Start() error

Start 开始对局:进入 running 并启动倒计时。重复 Start 报错(非法转移)。

func (*Match) Subscribe 

func (m *Match) Subscribe(ctx context.Context) (<-chan Event, func())

Subscribe 订阅对局事件流。返回只读 channel 与退订函数。 ctx 取消或调用退订函数即停止接收。

type Option 

type Option func(*config)

Option 配置 Match。

func WithDuration 

func WithDuration(d time.Duration) Option

WithDuration 设置对局时长(Start 后倒计时,默认 5 分钟)。

func WithEventBuffer 

func WithEventBuffer(n int) Option

WithEventBuffer 设置事件广播的每订阅者缓冲大小(默认 16)。

func WithOnEnd 

func WithOnEnd(fn func(Result)) Option

WithOnEnd 设置对局结束回调(到点或手动 Finish 均触发,仅触发一次)。

type Result 

type Result struct {
	ID     string
	Scores map[string]int64
	Winner string // 胜方;平局为 ""
	Tie    bool
}

Result 对局最终结果(OnEnd 回调 + EventEnded 携带)。

type Snapshot 

type Snapshot struct {
	ID        string           // 对局 ID
	Scores    map[string]int64 // 各阵营当前分
	Leader    string           // 领先阵营;平局为 ""
	Tie       bool             // 是否平局(最高分有多方并列)
	Running   bool             // 是否进行中
	Ended     bool             // 是否已结束
	Remaining time.Duration    // 剩余时间(ended 后为 0)
}

Snapshot 对局的即时快照。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.