《游戏服务端架构·规模化、全球化与成本》9.2 资源配额与混部

// file: internal/resourcequota/resourcequota.go
// tier: L1
// verify: go test ./internal/resourcequota/
package resourcequota

import (
	"errors"
	"fmt"
	"sort"
	"strings"
)

// Kind is a quota dimension. Units are fixed by the platform, not by the
// caller, so two products cannot compare CPU with different meanings.
type Kind string

const (
	CPU     Kind = "cpu_millicore"
	Memory  Kind = "memory_mib"
	Network Kind = "network_mbps"
)

// Quota is a hard ceiling for one product in one environment.
type Quota struct {
	Product string
	Env     string
	Limit   map[Kind]int64
}

// Request is one admission check. Amount is in the unit of its Kind.
type Request struct {
	Product string
	Env     string
	Kind    Kind
	Amount  int64
}

// Violation names the request index and the rule it broke.
type Violation struct {
	Index  int
	Reason string
}

func quotaKey(product, env string) string {
	return product + "/" + env
}

// Validate checks every request against its product/environment quota and
// against requests already accepted in the same batch. It never mutates the
// quota definitions.
func Validate(quotas []Quota, requests []Request) []Violation {
	limits := make(map[string]map[Kind]int64, len(quotas))
	for _, q := range quotas {
		key := quotaKey(q.Product, q.Env)
		if _, exists := limits[key]; exists {
			continue // first definition wins; duplicates are a config bug, not a request bug
		}
		limits[key] = q.Limit
	}

	used := make(map[string]int64)
	var out []Violation
	for i, r := range requests {
		if r.Amount <= 0 {
			out = append(out, Violation{Index: i, Reason: "amount must be positive"})
			continue
		}
		limit, ok := limits[quotaKey(r.Product, r.Env)]
		if !ok {
			out = append(out, Violation{Index: i, Reason: "no quota for product/environment"})
			continue
		}
		ceiling, ok := limit[r.Kind]
		if !ok {
			out = append(out, Violation{Index: i, Reason: "kind not declared in quota"})
			continue
		}
		key := quotaKey(r.Product, r.Env) + "|" + string(r.Kind)
		used[key] += r.Amount
		if used[key] > ceiling {
			out = append(out, Violation{Index: i, Reason: "quota exceeded"})
		}
	}
	return out
}

// Pool describes one schedulable resource pool.
type Pool struct {
	Capacity   int64   // provisioned units
	Guaranteed int64   // reserved for online-critical workloads
	Ratio      float64 // oversell ratio, >= 1
}

// Validate rejects configurations that would silently sell nothing or sell
// below the guaranteed reservation.
func (p Pool) Validate() error {
	if p.Capacity <= 0 {
		return errors.New("resourcequota: capacity must be positive")
	}
	if p.Guaranteed < 0 || p.Guaranteed > p.Capacity {
		return fmt.Errorf("resourcequota: guaranteed=%d outside [0,%d]", p.Guaranteed, p.Capacity)
	}
	if p.Ratio < 1 {
		return fmt.Errorf("resourcequota: ratio=%.2f must be >= 1", p.Ratio)
	}
	return nil
}

// Sellable is the total number of units the scheduler may hand out. It is
// floored to avoid promising a fraction of a CPU.
func (p Pool) Sellable() int64 {
	if p.Ratio <= 0 {
		return p.Capacity
	}
	return int64(float64(p.Capacity) * p.Ratio)
}

// Headroom is what is left after current usage. It may be negative when the
// pool is already over its sellable limit.
func (p Pool) Headroom(used int64) int64 {
	return p.Sellable() - used
}

// Admit answers whether a request fits. The returned headroom is computed
// before the request so callers can log the margin that was consumed.
func Admit(p Pool, used, request int64) (bool, int64) {
	headroom := p.Headroom(used)
	if request <= 0 || request > headroom {
		return false, headroom
	}
	return true, headroom
}

// Tier orders workloads by how acceptable it is to interrupt them.
type Tier int

const (
	TierOffline        Tier = iota // batch, backfill, report rebuild
	TierOnline                     // matchmaking, profile, shop
	TierOnlineCritical             // room servers serving live matches
)

// Workload is the minimum the eviction policy needs to know.
type Workload struct {
	Name        string
	Tier        Tier
	Priority    int   // larger means more important inside the same tier
	Reclaim     int64 // units freed if evicted
	StartedUnix int64
}

// EvictionOrder returns a copy sorted by "who gets killed first": offline
// before online, lower priority first, larger reclaim first, younger first,
// and finally name for a stable result.
func EvictionOrder(workloads []Workload) []Workload {
	out := append([]Workload(nil), workloads...)
	sort.SliceStable(out, func(i, j int) bool {
		a, b := out[i], out[j]
		if a.Tier != b.Tier {
			return a.Tier < b.Tier
		}
		if a.Priority != b.Priority {
			return a.Priority < b.Priority
		}
		if a.Reclaim != b.Reclaim {
			return a.Reclaim > b.Reclaim
		}
		if a.StartedUnix != b.StartedUnix {
			return a.StartedUnix > b.StartedUnix
		}
		return a.Name < b.Name
	})
	return out
}

// Shape is what a workload asks the node for when co-located.
type Shape struct {
	Name        string
	Tier        Tier
	Burstable   bool // may consume spare CPU when idle
	PinnedCPU   bool // owns dedicated cores
	MemoryLimit bool // hard memory cgroup
}

// Conflict is a rejected co-location pair with a reason.
type Conflict struct {
	A      string
	B      string
	Reason string
}

// CoLocationConflicts reports pairs that must not share a node. The rules
// encode the isolation the platform actually enforces, not a wish list.
func CoLocationConflicts(shapes []Shape) []Conflict {
	var out []Conflict
	for i := 0; i < len(shapes); i++ {
		for j := i + 1; j < len(shapes); j++ {
			a, b := shapes[i], shapes[j]
			switch {
			case a.Tier == TierOnlineCritical && b.Tier == TierOnlineCritical &&
				a.PinnedCPU && b.PinnedCPU:
				out = append(out, Conflict{A: a.Name, B: b.Name,
					Reason: "two pinned online-critical workloads compete for cores"})
			case a.Burstable && b.Tier == TierOnlineCritical && !a.MemoryLimit:
				out = append(out, Conflict{A: a.Name, B: b.Name,
					Reason: "burstable workload without memory limit may starve match server"})
			case b.Burstable && a.Tier == TierOnlineCritical && !b.MemoryLimit:
				out = append(out, Conflict{A: a.Name, B: b.Name,
					Reason: "burstable workload without memory limit may starve match server"})
			}
		}
	}
	sort.SliceStable(out, func(i, j int) bool {
		if out[i].A != out[j].A {
			return out[i].A < out[j].A
		}
		return out[i].B < out[j].B
	})
	return out
}

// Describe renders the quota table in a log-friendly, sorted form.
func Describe(quotas []Quota) string {
	lines := make([]string, 0, len(quotas))
	for _, q := range quotas {
		kinds := make([]string, 0, len(q.Limit))
		for k, v := range q.Limit {
			kinds = append(kinds, fmt.Sprintf("%s=%d", k, v))
		}
		sort.Strings(kinds)
		lines = append(lines, quotaKey(q.Product, q.Env)+" "+strings.Join(kinds, ","))
	}
	sort.Strings(lines)
	return strings.Join(lines, "; ")
}

cd .local/checks/gsarch-lab
go test -count=1 ./internal/resourcequota/
ok  gsarchlab/internal/resourcequota