《游戏服务端编程实践》8.3.1 帧号与预测机制

// file: ch08/lockstep/frame.go
// tier: L1
// verify: go test ./ch08/lockstep/

package lockstep

import "errors"

// Frame 是逻辑帧号，允许自然回绕。比较必须使用 After/Sub，不能直接用 <。
type Frame uint32

// Sub 返回 f-o 的有符号差值，跨回绕仍然正确。
func (f Frame) Sub(o Frame) int32 { return int32(f - o) }

// After 报告 f 是否严格晚于 o。
func (f Frame) After(o Frame) bool { return int32(f-o) > 0 }

var (
	ErrFrameStale   = errors.New("frame: stale or duplicate frame")
	ErrFrameExpired = errors.New("frame: requested frame expired")
	ErrFrameAhead   = errors.New("frame: requested frame ahead of latest")
)

// FrameBuffer 保存最近 capacity 帧的权威状态，帧号必须连续递增。
type FrameBuffer[T any] struct {
	capacity int
	latest   Frame
	started  bool
	states   map[Frame]T
	order    []Frame
}

func NewFrameBuffer[T any](capacity int) *FrameBuffer[T] {
	if capacity < 1 {
		capacity = 1
	}
	return &FrameBuffer[T]{capacity: capacity, states: make(map[Frame]T)}
}

// Put 写入下一帧状态。帧号必须严格等于 latest+1，否则返回 ErrFrameStale。
func (b *FrameBuffer[T]) Put(f Frame, state T) error {
	if b.started && !f.After(b.latest) {
		return ErrFrameStale
	}
	if b.started && f != b.latest+1 {
		return ErrFrameStale
	}
	b.states[f] = state
	b.order = append(b.order, f)
	b.latest = f
	b.started = true
	for len(b.order) > b.capacity {
		old := b.order[0]
		b.order = b.order[1:]
		delete(b.states, old)
	}
	return nil
}

// Get 返回指定帧的状态，已被容量淘汰时 ok 为 false。
func (b *FrameBuffer[T]) Get(f Frame) (T, bool) {
	s, ok := b.states[f]
	return s, ok
}

// Latest 返回最新帧。
func (b *FrameBuffer[T]) Latest() (Frame, bool) { return b.latest, b.started }

// Rollback 返回确认帧的权威状态；过旧返回 ErrFrameExpired，超前返回 ErrFrameAhead。
func (b *FrameBuffer[T]) Rollback(f Frame) (T, error) {
	var zero T
	if !b.started {
		return zero, ErrFrameExpired
	}
	if f.After(b.latest) {
		return zero, ErrFrameAhead
	}
	s, ok := b.states[f]
	if !ok {
		return zero, ErrFrameExpired
	}
	return s, nil
}

// file: ch08/lockstep/frame_test.go
// tier: L1
// verify: go test ./ch08/lockstep/

package lockstep

import (
	"errors"
	"math"
	"testing"
)

func TestFrameWrapComparison(t *testing.T) {
	last := Frame(math.MaxUint32)
	if !Frame(0).After(last) {
		t.Fatalf("frame 0 should be after %d", last)
	}
	if Frame(0).Sub(last) != 1 {
		t.Fatalf("wrap diff = %d, want 1", Frame(0).Sub(last))
	}
	if Frame(last).After(Frame(0)) {
		t.Fatal("last frame must not be after frame 0")
	}
	if Frame(10).After(Frame(10)) {
		t.Fatal("equal frame must not be after itself")
	}
}

func TestFrameBufferRollbackReplay(t *testing.T) {
	deltas := []uint64{0, 3, 5, 2, 7, 4, 6, 1, 2}
	buf := NewFrameBuffer[uint64](8)
	var pos uint64
	for f := Frame(1); f <= 5; f++ {
		pos += deltas[f]
		if err := buf.Put(f, pos); err != nil {
			t.Fatal(err)
		}
	}
	// 客户端本地已经预测执行到第 8 帧。
	local := pos
	for f := Frame(6); f <= 8; f++ {
		local += deltas[f]
	}

	confirmed, err := buf.Rollback(5)
	if err != nil {
		t.Fatal(err)
	}
	replay := confirmed
	for f := Frame(6); f <= 8; f++ {
		replay += deltas[f]
	}
	if replay != local {
		t.Fatalf("replay = %d, local prediction = %d", replay, local)
	}
	if got, ok := buf.Get(4); !ok || got != 17 {
		t.Fatalf("frame 4 = %d, %v; want 17, true", got, ok)
	}
}

func TestFrameBufferRejectsExpiredAndAhead(t *testing.T) {
	buf := NewFrameBuffer[uint64](3)
	for f := Frame(1); f <= 6; f++ {
		if err := buf.Put(f, uint64(f)*10); err != nil {
			t.Fatal(err)
		}
	}
	if _, err := buf.Rollback(1); !errors.Is(err, ErrFrameExpired) {
		t.Fatalf("want ErrFrameExpired, got %v", err)
	}
	if _, err := buf.Rollback(9); !errors.Is(err, ErrFrameAhead) {
		t.Fatalf("want ErrFrameAhead, got %v", err)
	}
	if _, ok := buf.Get(2); ok {
		t.Fatal("frame 2 should be evicted by capacity 3")
	}
	if got, ok := buf.Get(6); !ok || got != 60 {
		t.Fatalf("frame 6 = %d, %v; want 60, true", got, ok)
	}
	if err := buf.Put(6, 0); !errors.Is(err, ErrFrameStale) {
		t.Fatalf("want ErrFrameStale, got %v", err)
	}
	if err := buf.Put(8, 0); !errors.Is(err, ErrFrameStale) {
		t.Fatalf("gap write: want ErrFrameStale, got %v", err)
	}
}

cd .local/checks/gs-practice-lab && gofmt -l ch08/lockstep && go vet ./ch08/lockstep/ && go test ./ch08/lockstep/ -count=1

ok  	gspractice/ch08/lockstep	0.371s