《MMO 服务器开发》17.3 实例分配与回收

// file: internal/match/pool.go
// tier: L1
// verify: go test ./internal/match/
package match

import (
	"errors"
	"sync"
)

// InstanceID 是地图实例 ID（卷二共享类型，uint64）。
type InstanceID uint64

var (
	// ErrNoInstance 表示池内没有可用的空闲实例。
	ErrNoInstance = errors.New("match: 实例池已耗尽，无可用实例")
	// ErrUnknownInstance 表示分配/回收了一个池内不存在的实例。
	ErrUnknownInstance = errors.New("match: 未知实例 ID")
)

// Instance 是一个单服内的地图实例。卷二只做单服实例池，
// 真正的跨服调度（哪个大区、哪台物理机）留到卷三。
type Instance struct {
	ID            InstanceID
	Capacity      int
	State         string // idle | allocated | draining
	CooldownUntil int64  // draining 期间不可复用的截止时刻(ms)
	Uses          int    // 累计被分配次数，用于灰度与磨损观测
}

// Pool 是单服内的实例池，带预热、best-fit 分配与冷却回收。
type Pool struct {
	mu        sync.Mutex
	instances []*Instance
	nextID    InstanceID
	cooldown  int64
	allocated int
	recycled  int
}

// NewPool 预热 n 个容量为 capacity 的实例，回收冷却 cooldown 毫秒。
func NewPool(n, capacity int, cooldown int64) *Pool {
	p := &Pool{cooldown: cooldown}
	for i := 0; i < n; i++ {
		p.nextID++
		p.instances = append(p.instances, &Instance{ID: p.nextID, Capacity: capacity, State: "idle"})
	}
	return p
}

// Allocate 按 best-fit 挑一个容量 ≥ need 的空闲实例：优先刚好够用的，
// 免得一个 50 人副本吃掉能装 200 人的世界实例。
func (p *Pool) Allocate(need int, now int64) (*Instance, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	var best *Instance
	for _, in := range p.instances {
		if in.State != "idle" || now < in.CooldownUntil || in.Capacity < need {
			continue
		}
		if best == nil || in.Capacity < best.Capacity {
			best = in
		}
	}
	if best == nil {
		return nil, ErrNoInstance
	}
	best.State = "allocated"
	best.Uses++
	p.allocated++
	return best, nil
}

// Release 把实例置为 draining 并进入冷却；冷却结束前 Allocate 不会碰它。
// 冷却的意义是：上一局的残留状态（AI、掉落、缓存）需要时间被清干净。
func (p *Pool) Release(id InstanceID, now int64) error {
	p.mu.Lock()
	defer p.mu.Unlock()
	in := p.find(id)
	if in == nil {
		return ErrUnknownInstance
	}
	in.State = "draining"
	in.CooldownUntil = now + p.cooldown
	p.recycled++
	return nil
}

// Tick 把冷却到期的 draining 实例重新标为 idle，使其回到可分配集合。
func (p *Pool) Tick(now int64) int {
	p.mu.Lock()
	defer p.mu.Unlock()
	n := 0
	for _, in := range p.instances {
		if in.State == "draining" && now >= in.CooldownUntil {
			in.State = "idle"
			in.CooldownUntil = 0
			n++
		}
	}
	return n
}

func (p *Pool) find(id InstanceID) *Instance {
	for _, in := range p.instances {
		if in.ID == id {
			return in
		}
	}
	return nil
}

// Stats 返回 (总实例数, 空闲数, 累计分配数, 累计回收数)。
func (p *Pool) Stats() (total, idle, allocated, recycled int) {
	p.mu.Lock()
	defer p.mu.Unlock()
	for _, in := range p.instances {
		if in.State == "idle" {
			idle++
		}
	}
	return len(p.instances), idle, p.allocated, p.recycled
}

// snippet: internal/match/pool_test.go（摘录）
// best-fit：需求 20 人时，200 人的世界实例不该被吃掉，应优先给 20 人实例。
func TestAllocateBestFit(t *testing.T) {
	p := NewPool(0, 0, 0)
	p.instances = []*Instance{
		{ID: 1, Capacity: 200, State: "idle"},
		{ID: 2, Capacity: 50, State: "idle"},
		{ID: 3, Capacity: 20, State: "idle"},
	}
	in, err := p.Allocate(20, 0)
	if err != nil || in.ID != 3 {
		t.Fatalf("best-fit 选中 %v (err=%v)，期望 ID=3", in, err)
	}
}

// 冷却：释放后到冷却结束前不可复用，Tick 到期后才回到空闲集合。
func TestRecycleCooldown(t *testing.T) {
	const cd = 5000
	p := NewPool(1, 10, cd)
	in, _ := p.Allocate(1, 0)
	p.Release(in.ID, 0)
	if in.State != "draining" {
		t.Fatalf("释放后状态 %q，期望 draining", in.State)
	}
	if _, err := p.Allocate(1, cd-1); !errors.Is(err, ErrNoInstance) {
		t.Fatalf("冷却期内不该可分配，实际 %v", err)
	}
	if n := p.Tick(cd); n != 1 {
		t.Fatalf("冷却到期应转回 1 个实例，实际 %d", n)
	}
	again, err := p.Allocate(1, cd)
	if err != nil || again.Uses != 2 {
		t.Fatalf("复用失败或 Uses=%d，期望 2", again.Uses)
	}
}

// 池耗尽：全部占用后 Allocate 必须返回 ErrNoInstance。
func TestPoolExhausted(t *testing.T) {
	p := NewPool(2, 10, 0)
	p.Allocate(5, 0)
	p.Allocate(5, 0)
	if _, err := p.Allocate(5, 0); !errors.Is(err, ErrNoInstance) {
		t.Fatalf("耗尽时应返回 ErrNoInstance，实际 %v", err)
	}
}

$ go test ./internal/match/
ok  	aegis/internal/match	1.170s     （19 个 test 全绿，含 7 个实例池用例）