《MMO 服务器开发》3.2 实例创建与回收

// file: internal/scene/instance.go
// tier: L1
// verify: go test ./internal/scene/
package scene

import (
	"errors"
	"sync"
)

// InstanceID 是地图实例 ID：全服唯一，单调递增，不复用已回收的号。
type InstanceID uint64

// EntityID 高 16 位是实例号，低 48 位是实例内自增序号。
// 同一个玩家换实例时实体 ID 会变，但 (实例号, 序号) 在任何时刻都唯一。
type EntityID uint64

const entitySeqMask = 1<<48 - 1

// MakeEntityID 按「高 16 位实例号 + 低 48 位序号」拼出实体 ID。
func MakeEntityID(inst InstanceID, seq uint64) EntityID {
	return EntityID(uint64(uint16(inst))<<48 | (seq & entitySeqMask))
}

// InstanceOf 从实体 ID 反解出它所属的实例号。
func InstanceOf(e EntityID) InstanceID { return InstanceID(uint64(e) >> 48) }

// SeqOf 从实体 ID 反解出实例内序号。
func SeqOf(e EntityID) uint64 { return uint64(e) & entitySeqMask }

// InstanceState 是实例生命周期状态机：Active -> Draining -> Closed。
type InstanceState uint8

const (
	InstActive   InstanceState = iota // 正常接人
	InstDraining                      // 不再进人，等现有玩家离开
	InstClosed                        // 已回收，可被对象池复用
)

var (
	ErrNoInstance   = errors.New("scene: 实例不存在或已关闭")
	ErrInstanceFull = errors.New("scene: 实例已达人数上限")
)

// Instance 是一个地图实例：持有地图模板的引用 + 本实例的玩家集合。
type Instance struct {
	ID       InstanceID
	Map      *MapData
	state    InstanceState
	players  map[uint64]struct{} // PlayerID 集合
	capacity int
	created  int64 // 创建时的逻辑帧
	lastAct  int64 // 最后一次有玩家进出/活动的帧
}

func (i *Instance) PlayerCount() int     { return len(i.players) }
func (i *Instance) State() InstanceState { return i.state }

// InstanceManager 统一管理实例的创建、进出与回收。
// 它是所有场景 goroutine 的汇聚点，因此用一把互斥锁保护，内部全是 O(1) 操作。
type InstanceManager struct {
	mu       sync.Mutex
	next     uint64
	live     map[InstanceID]*Instance
	pool     []*Instance
	ttlTicks int64 // 空实例闲置超过这么多帧就回收
	capacity int   // 单实例人数上限
}

// NewInstanceManager：ttlTicks 是空实例保活帧数，capacity 是单实例上限。
func NewInstanceManager(ttlTicks int64, capacity int) *InstanceManager {
	if ttlTicks < 0 {
		ttlTicks = 0
	}
	return &InstanceManager{
		live:     make(map[InstanceID]*Instance),
		ttlTicks: ttlTicks,
		capacity: capacity,
	}
}

// Create 开一个新实例。地图模板 md 由所有实例共享，不复制。
func (m *InstanceManager) Create(md *MapData, tick int64) *Instance {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.next++
	inst := m.take()
	inst.ID = InstanceID(m.next)
	inst.Map = md
	inst.state = InstActive
	inst.capacity = m.capacity
	inst.created = tick
	inst.lastAct = tick
	m.live[inst.ID] = inst
	return inst
}

// take 从对象池取一个实例复用；池空则新建。返回的实例 players 已清空。
func (m *InstanceManager) take() *Instance {
	n := len(m.pool)
	if n == 0 {
		return &Instance{players: make(map[uint64]struct{})}
	}
	inst := m.pool[n-1]
	m.pool = m.pool[:n-1]
	clear(inst.players)
	return inst
}

// put 把实例放回对象池；players 里的内存保留复用，只清空键。
func (m *InstanceManager) put(inst *Instance) {
	inst.state = InstClosed
	inst.Map = nil
	clear(inst.players)
	m.pool = append(m.pool, inst)
}

// Enter 把一个玩家放进实例。满员或状态不对都返回错误。
func (m *InstanceManager) Enter(id InstanceID, player uint64, tick int64) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	inst, ok := m.live[id]
	if !ok {
		return ErrNoInstance
	}
	if inst.state != InstActive {
		return ErrNoInstance
	}
	if len(inst.players) >= inst.capacity {
		return ErrInstanceFull
	}
	inst.players[player] = struct{}{}
	inst.lastAct = tick
	return nil
}

// Leave 把玩家移出实例；实例转空时更新闲置计时。
func (m *InstanceManager) Leave(id InstanceID, player uint64, tick int64) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	inst, ok := m.live[id]
	if !ok {
		return ErrNoInstance
	}
	delete(inst.players, player)
	inst.lastAct = tick
	return nil
}

// Get 返回实例的只读快照信息（人数与状态）。
func (m *InstanceManager) Get(id InstanceID) (int, InstanceState, bool) {
	m.mu.Lock()
	defer m.mu.Unlock()
	inst, ok := m.live[id]
	if !ok {
		return 0, InstClosed, false
	}
	return len(inst.players), inst.state, true
}

// CollectGarbage 回收「空且闲置超过 ttl 帧」的实例，返回被回收的 ID 列表。
// 调用方通常在逻辑帧循环里每隔若干帧调一次。
func (m *InstanceManager) CollectGarbage(tick int64) []InstanceID {
	m.mu.Lock()
	defer m.mu.Unlock()
	var freed []InstanceID
	for id, inst := range m.live {
		if len(inst.players) == 0 && tick-inst.lastAct >= m.ttlTicks {
			delete(m.live, id)
			m.put(inst)
			freed = append(freed, id)
		}
	}
	return freed
}

func (m *InstanceManager) LiveCount() int {
	m.mu.Lock()
	defer m.mu.Unlock()
	return len(m.live)
}

func (m *InstanceManager) PoolSize() int {
	m.mu.Lock()
	defer m.mu.Unlock()
	return len(m.pool)
}

// snippet: internal/scene/instance_test.go（摘录）
func TestCollectGarbageRecyclesToPool(t *testing.T) {
	m, _ := NewMapData(1, 8, 8)
	im := NewInstanceManager(5, 4)

	a := im.Create(m, 0)
	im.Enter(a.ID, 1, 0) // 非空，不该被回收
	b := im.Create(m, 0) // 一直空
	bID := b.ID          // 对象会被复用，先记住它的 ID

	// 只过了 3 帧，未到 ttl，不该回收。
	if freed := im.CollectGarbage(3); len(freed) != 0 {
		t.Fatalf("3 帧后回收了 %v，期望不回收", freed)
	}
	// 到 5 帧：空的 b 被回收，非空的 a 保留。
	freed := im.CollectGarbage(5)
	if len(freed) != 1 || freed[0] != bID {
		t.Fatalf("回收 = %v，期望只回收 %d", freed, bID)
	}
	if im.LiveCount() != 1 {
		t.Fatalf("存活实例 = %d，期望 1", im.LiveCount())
	}
	if im.PoolSize() != 1 {
		t.Fatalf("池大小 = %d，期望 1", im.PoolSize())
	}
	// 再开一个：必须复用池里的对象，池清空，ID 继续递增不复用。
	c := im.Create(m, 6)
	if im.PoolSize() != 0 {
		t.Fatalf("复用后池 = %d，期望 0", im.PoolSize())
	}
	if c.ID == bID {
		t.Fatalf("复用对象却复用了 ID：%d", c.ID)
	}
	if c.PlayerCount() != 0 {
		t.Fatalf("复用实例残留玩家：%d", c.PlayerCount())
	}
}

// file: internal/scene/bench_test.go
// tier: B
// verify: go test -bench=Instance -benchmem ./internal/scene/
package scene

import "testing"

// benchSink 让「不池化」路径的实例逃逸到堆上，避免被编译器优化掉。
var benchSink []*Instance

// 池化：Create 拿到的是池里复用的对象，回收时只清键、不重建 map。
func BenchmarkInstancePooledLifecycle(b *testing.B) {
	m, _ := NewMapData(1, 64, 64)
	im := NewInstanceManager(0, 64) // ttl=0：空实例立刻回收进池
	b.ReportAllocs()
	for i := 0; i < b.N; i++ {
		inst := im.Create(m, 0)
		im.Enter(inst.ID, 1, 0)
		im.Leave(inst.ID, 1, 0)
		im.CollectGarbage(0)
	}
}

// 不池化：每个循环重新 new 一个实例对象 + 一张 players map，作为对照。
func BenchmarkInstanceFreshAlloc(b *testing.B) {
	m, _ := NewMapData(1, 64, 64)
	b.ReportAllocs()
	benchSink = make([]*Instance, 0, 1)
	for i := 0; i < b.N; i++ {
		inst := &Instance{Map: m, state: InstActive, players: make(map[uint64]struct{})}
		inst.players[1] = struct{}{}
		benchSink = benchSink[:0]
		benchSink = append(benchSink, inst)
	}
}

$ go test -bench=Instance -benchmem -run '^$' ./internal/scene/
BenchmarkInstancePooledLifecycle-10    	 9782132	121.8 ns/op	  8 B/op	1 allocs/op
BenchmarkInstanceFreshAlloc-10         	12389984	 95.22 ns/op	256 B/op	3 allocs/op
PASS
ok  	aegis/internal/scene	2.781s