Build seats yield to one shared slice per node; the composer half waits for the engines (ADR 0553, issue 1806)

Review round 1: the decoder type ships before any composer can emit it, so a
routine SDK bump never sends yields to an engine that refuses them; the
composer half moves to a later change. Every yielding process of a node goes
into one top-level slice, meshyield.slice, so the three build modules share one
quota instead of taking one each; the share is one node value, node-tools'
build-cpu-share, and each step's threads divide it by every build slot of the
node (words from the composer, a conservative fallback without them).
This commit is contained in:
2026-10-26 14:20:05 +01:00
parent 76deab6c67
commit 852ba81c5a
11 changed files with 205 additions and 318 deletions
+97 -127
View File
@@ -1,94 +1,50 @@
// Package buildcpu is how much of a build node's processors its builds may take, and how they yield to everything else
// there (novox/hq issue 1806; the operator, 2026-10-26: "limit CPU usage on our build nodes so the total cpu usage never
// impacts the normal workings of our nodes").
// there (novox/hq ADR 0553, issue 1806; the operator, 2026-10-26: "limit CPU usage on our build nodes so the total cpu
// usage never impacts the normal workings of our nodes ... We have 3 build agents so they should share the cpu power").
//
// Three parts, each with one owner:
//
// - **Priority.** A build seat's holder (catalogue.Seat.Yields) runs at the lowest CPU and IO priority there is: the
// composer gives its runtime process declaration.Yields, and the node-engine writes it into the unit as
// CPUWeight=idle, IOWeight=1, Nice=19 and the best-effort IO class at its lowest level. Interactive and service
// work always comes first; builds take the cycles nothing else wants.
// - **The cap.** The build modules' setting `cpu-cap` (Setting) gives each node the share of its processors its builds
// may take at most, as `<node>=<percent>` pairs. The composer turns this node's share into Yields.CPUShare, and the
// node-engine into CPUQuota for the machine's processor count: a hard bound, held by the kernel.
// - **Threads.** Inside that bound a step starts no more threads than its part of it (Threads): GOMAXPROCS, `go
// test -p`, the Node test runner's concurrency. A step with more runnable threads than its quota only waits in the
// kernel's throttle, and its timeouts with it.
// - **Priority.** A build seat's holder (catalogue.Seat.Yields) runs at the lowest priority there is: the composer
// gives its runtime process declaration.Yields, and the node-engine places every yielding process of the node in
// one slice (declaration.YieldSlice) whose CPU weight is idle, with Nice=19 for every process it starts.
// Interactive and service work always comes first; builds take the cycles nothing else wants.
// - **One cap per node, shared.** The node's share of its processors is one value, the node-tools runtime's setting
// `build-cpu-share` (ShareSetting), set per node through the node's settings layer. The node-engine writes it as the
// slice's CPUQuota: one bound the kernel holds for all the node's build modules together, never one per module.
// - **Threads.** Inside that bound a step starts no more threads than its part of it (Threads): the node's share
// divided by every build slot of the node, across all its build modules (the composer hands both as words,
// ShareWord and SlotsWord). GOMAXPROCS sets every go command's -p, the compiler's concurrency, a test binary's
// processors and -parallel.
package buildcpu
import (
"fmt"
"os"
"runtime"
"sort"
"strconv"
"strings"
)
// Setting is the build modules' setting of each node's processor cap: `<node>=<percent>` pairs separated by commas,
// such as `shanks=50,ace=75`; a percent sign after the number is allowed. Each build module declares it with Defaults
// as its default.
const Setting = "cpu-cap"
// ShareSetting is the node-tools runtime's setting of the node's processor share for its builds, in percent of the
// machine's processors, 1 to 100: one value per node, set through the node's settings layer (novox/hq ADR 0553 §3).
const ShareSetting = "build-cpu-share"
// Defaults is the setting's default: the operator's two desktops (shanks, g14) keep half their processors for
// themselves at all times, and ace, a server, builds on three quarters. A node it does not name has DefaultPercent.
const Defaults = "shanks=50,g14=50,ace=75"
// DefaultPercent is the cap of a node the setting does not name.
// DefaultPercent is the share where nothing sets one: half the machine, so a desktop keeps half its processors for
// itself whatever builds.
const DefaultPercent = 50
// Parse reads the setting's pairs. A percent outside 1 to 100 is refused: 0 would stop every build without pausing the
// seat (the capacity setting says that, with 0 asks), and more than 100 is no cap.
func Parse(s string) (map[string]int, error) {
out := map[string]int{}
for _, pair := range strings.Split(s, ",") {
pair = strings.TrimSpace(pair)
if pair == "" {
continue
}
node, value, ok := strings.Cut(pair, "=")
node = strings.TrimSpace(node)
value = strings.TrimSuffix(strings.TrimSpace(value), "%")
n, err := strconv.Atoi(strings.TrimSpace(value))
if !ok || node == "" || err != nil || n < 1 || n > 100 {
return nil, fmt.Errorf("the processor cap %q is not <node>=<percent of its processors, 1 to 100>", pair)
}
if _, dup := out[node]; dup {
return nil, fmt.Errorf("the processor cap names %s twice", node)
}
out[node] = n
}
return out, nil
}
// BuildSeats is how many seats yield (catalogue.Seat.Yields): one build module per language. A step that is told no
// node-wide slot count assumes every one of them runs its full capacity beside it.
const BuildSeats = 3
// Of is node's cap in percent of its processors: DefaultPercent for a node the setting does not name.
func Of(setting, node string) (int, error) {
caps, err := Parse(setting)
if err != nil {
return 0, err
}
if n, ok := caps[node]; ok {
return n, nil
}
return DefaultPercent, nil
}
// The words the composer gives every yielding module (novox/hq ADR 0553 §4): the node's share, and every build slot
// of the node across all its yielding modules.
const (
ShareWord = "MESH_BUILD_CPU_SHARE"
SlotsWord = "MESH_BUILD_SLOTS"
)
// Format is a cap map in the setting's own words, sorted by node.
func Format(caps map[string]int) string {
nodes := make([]string, 0, len(caps))
for n := range caps {
nodes = append(nodes, n)
}
sort.Strings(nodes)
parts := make([]string, 0, len(nodes))
for _, n := range nodes {
parts = append(parts, fmt.Sprintf("%s=%d", n, caps[n]))
}
return strings.Join(parts, ",")
}
// Quota is the unit's CPUQuota for a share of a machine with cores processors: systemd counts a quota in percent of
// one processor, so half of 24 is 1200%. At least 100%, one processor, so a cap on a small machine never stops a step.
// Quota is a CPUQuota for a share of a machine with cores processors: systemd counts a quota in percent of one
// processor, so half of 24 is 1200%. At least 100%, one processor, so a share on a small machine never stops a step.
func Quota(percent, cores int) int {
q := percent * cores
if q < 100 {
@@ -97,14 +53,14 @@ func Quota(percent, cores int) int {
return q
}
// Threads is how many threads one step may run at once: its part of the cap when slots steps run beside it, at least
// one. Rounded down, so the steps together stay inside the quota.
// Threads is how many threads one step may run at once: its part of the share when slots steps may run on the node
// at once, at least one. Rounded down, so the steps together stay inside the quota.
func Threads(percent, cores, slots int) int {
if slots < 1 {
slots = 1
}
if percent < 1 || percent > 100 {
percent = 100
percent = DefaultPercent
}
t := cores * percent / 100 / slots
if t < 1 {
@@ -115,28 +71,36 @@ func Threads(percent, cores, slots int) int {
// Limits is what one step is held to on this node, as a status tool says it.
type Limits struct {
// Percent is the node's cap in percent of its processors, and Setting the words it came from.
Percent int `json:"cap-percent"`
Setting string `json:"cap-setting"`
// Percent is the node's share in percent of its processors; From says where it was read: the composer's word,
// or the default.
Percent int `json:"share-percent"`
From string `json:"share-from"`
// Cores is the machine's processor count.
Cores int `json:"cores"`
// Slots is the node's build capacity: steps at once.
Slots int `json:"slots"`
// Slots is every build slot of the node, across all its build modules; SlotsFrom where it was read.
Slots int `json:"node-slots"`
SlotsFrom string `json:"slots-from"`
// Threads is what each step is given (Threads).
Threads int `json:"threads-per-step"`
}
// LimitsFor is the limits of a step on node, from the cap setting and the node's capacity. A setting that cannot be read
// gives the default cap and says why in the error, so a step still runs with a bound rather than none.
func LimitsFor(setting, node string, slots int) (Limits, error) {
l := Limits{Setting: setting, Cores: runtime.NumCPU(), Slots: slots}
p, err := Of(setting, node)
if err != nil {
p = DefaultPercent
// FromWords is the limits of a step from the words the composer gave this process (ShareWord, SlotsWord). Where a word
// is absent or not a number: the default share, and own × BuildSeats slots. A module told nothing assumes every build
// module of the node runs its full capacity beside it, so the steps together never take more than the default share.
func FromWords(getenv func(string) string, own int) Limits {
if own < 1 {
own = 1
}
l.Percent = p
l.Threads = Threads(p, l.Cores, slots)
return l, err
l := Limits{Percent: DefaultPercent, From: "default", Cores: runtime.NumCPU(), Slots: own * BuildSeats,
SlotsFrom: "own capacity × " + strconv.Itoa(BuildSeats) + " build seats"}
if n, err := strconv.Atoi(strings.TrimSpace(getenv(ShareWord))); err == nil && n >= 1 && n <= 100 {
l.Percent, l.From = n, ShareWord
}
if n, err := strconv.Atoi(strings.TrimSpace(getenv(SlotsWord))); err == nil && n >= 1 {
l.Slots, l.SlotsFrom = n, SlotsWord
}
l.Threads = Threads(l.Percent, l.Cores, l.Slots)
return l
}
// Env is the environment a step's commands are given so they start no more threads than they may: GOMAXPROCS for every
@@ -150,32 +114,30 @@ func Env(threads int) []string {
return []string{"GOMAXPROCS=" + t, "UV_THREADPOOL_SIZE=" + t}
}
// WithEnv is env with Env(threads) in place of any GOMAXPROCS or UV_THREADPOOL_SIZE it carried.
func WithEnv(env []string, threads int) []string {
out := make([]string, 0, len(env)+2)
for _, kv := range env {
if strings.HasPrefix(kv, "GOMAXPROCS=") || strings.HasPrefix(kv, "UV_THREADPOOL_SIZE=") {
continue
}
out = append(out, kv)
}
return append(out, Env(threads)...)
// InForce is what the kernel holds this process to, read rather than assumed (evidence over assertion): its nice
// level, its cgroup (the unit) and the cgroup's parent (the slice the node-engine placed it in), each one's CPU weight,
// idle mark and quota. A field the machine does not answer is left empty and Unread says which.
//
// The IO weight is read but binds only where the disk's scheduler honours it (bfq, or the io.cost controller); under
// the scheduler `none`, the usual one for NVMe, it does nothing, and the CPU bound is what holds.
type InForce struct {
Nice int `json:"nice"`
Cgroup string `json:"cgroup,omitempty"`
Unit Group `json:"unit"`
Slice Group `json:"slice"`
// Quota is the tighter of the two groups' cpu.max as a percent of one processor, 0 with none.
Quota int `json:"quota-percent,omitempty"`
Unread []string `json:"unread,omitempty"`
}
// InForce is what the kernel holds this process to, read rather than assumed (evidence over assertion): its nice
// level, its cgroup, the cgroup's CPU weight, idle mark and quota. A field the machine does not answer is left empty
// and Unread says which.
type InForce struct {
Nice int `json:"nice"`
Cgroup string `json:"cgroup,omitempty"`
// Group is one cgroup's controls.
type Group struct {
Path string `json:"path,omitempty"`
CPUIdle string `json:"cpu-idle,omitempty"`
CPUWeight string `json:"cpu-weight,omitempty"`
// CPUMax is the cgroup's cpu.max: "<quota µs> <period µs>", or "max" with no quota.
CPUMax string `json:"cpu-max,omitempty"`
// Quota is CPUMax as a percent of one processor, 0 with none.
Quota int `json:"quota-percent,omitempty"`
IOWeight string `json:"io-weight,omitempty"`
Unread []string `json:"unread,omitempty"`
CPUMax string `json:"cpu-max,omitempty"`
IOWeight string `json:"io-weight,omitempty"`
}
// cgroupRoot is where the unified hierarchy is mounted. A variable so a test can point it elsewhere.
@@ -184,6 +146,9 @@ var cgroupRoot = "/sys/fs/cgroup"
// procSelfCgroup is this process's cgroup file. A variable so a test can point it elsewhere.
var procSelfCgroup = "/proc/self/cgroup"
// procSelfStat is this process's stat file. A variable so a test can point it elsewhere.
var procSelfStat = "/proc/self/stat"
// ReadInForce reads what the kernel holds this process to.
func ReadInForce() InForce {
var f InForce
@@ -202,20 +167,28 @@ func ReadInForce() InForce {
f.Unread = append(f.Unread, "cgroup: not on the unified hierarchy")
return f
}
dir := cgroupRoot + f.Cgroup
read := func(name string) string {
b, err := os.ReadFile(dir + "/" + name)
if err != nil {
f.Unread = append(f.Unread, name+": "+err.Error())
return ""
read := func(path string) Group {
g := Group{Path: path}
value := func(name string) string {
b, err := os.ReadFile(cgroupRoot + path + "/" + name)
if err != nil {
f.Unread = append(f.Unread, path+"/"+name+": "+err.Error())
return ""
}
return strings.TrimSpace(string(b))
}
g.CPUIdle, g.CPUWeight, g.CPUMax, g.IOWeight = value("cpu.idle"), value("cpu.weight"), value("cpu.max"), value("io.weight")
return g
}
f.Unit = read(f.Cgroup)
if i := strings.LastIndex(f.Cgroup, "/"); i > 0 {
f.Slice = read(f.Cgroup[:i])
}
for _, q := range []int{quotaOf(f.Unit.CPUMax), quotaOf(f.Slice.CPUMax)} {
if q > 0 && (f.Quota == 0 || q < f.Quota) {
f.Quota = q
}
return strings.TrimSpace(string(b))
}
f.CPUIdle = read("cpu.idle")
f.CPUWeight = read("cpu.weight")
f.CPUMax = read("cpu.max")
f.IOWeight = read("io.weight")
f.Quota = quotaOf(f.CPUMax)
return f
}
@@ -233,9 +206,6 @@ func quotaOf(cpuMax string) int {
return q * 100 / p
}
// procSelfStat is this process's stat file. A variable so a test can point it elsewhere.
var procSelfStat = "/proc/self/stat"
// nice is this process's nice level from its stat file (the 19th field, counted after the command's closing
// parenthesis, which may itself hold spaces); 0 when it cannot be read.
func nice() int {
+50 -54
View File
@@ -4,77 +4,72 @@ import (
"os"
"path/filepath"
"reflect"
"runtime"
"testing"
)
// The cap's words, a node's share, the unit quota and the threads a step is given, in one table (issue 1806).
func TestCapQuotaAndThreads(t *testing.T) {
// The node's share as a quota, the threads one step is given across every build slot of the node, and the words the
// composer hands, in one table (ADR 0553, issue 1806).
func TestShareQuotaAndThreads(t *testing.T) {
for _, c := range []struct {
name, setting, node string
cores, slots int
percent, quota int
threads int
refused bool
name string
percent, cores, slots int
quota, threads int
}{
{name: "default for shanks", setting: Defaults, node: "shanks", cores: 24, slots: 3, percent: 50, quota: 1200, threads: 4},
{name: "default for ace", setting: Defaults, node: "ace", cores: 24, slots: 2, percent: 75, quota: 1800, threads: 9},
{name: "default for g14", setting: Defaults, node: "g14", cores: 16, slots: 1, percent: 50, quota: 800, threads: 8},
{name: "a node not named", setting: Defaults, node: "novox", cores: 8, slots: 1, percent: DefaultPercent, quota: 400, threads: 4},
{name: "percent sign and spaces", setting: " shanks = 25% ", node: "shanks", cores: 24, slots: 3, percent: 25, quota: 600, threads: 2},
{name: "one processor at least", setting: "tiny=10", node: "tiny", cores: 2, slots: 4, percent: 10, quota: 100, threads: 1},
{name: "zero slots counts as one", setting: "x=100", node: "x", cores: 4, slots: 0, percent: 100, quota: 400, threads: 4},
{name: "zero refused", setting: "shanks=0", node: "shanks", refused: true},
{name: "over a hundred refused", setting: "shanks=150", node: "shanks", refused: true},
{name: "no number refused", setting: "shanks", node: "shanks", refused: true},
{name: "twice refused", setting: "a=1,a=2", node: "a", refused: true},
{"shanks: half of 24 across 9 slots", 50, 24, 9, 1200, 1},
{"shanks: half of 24 across 4 slots", 50, 24, 4, 1200, 3},
{"ace: three quarters of 24 across 6 slots", 75, 24, 6, 1800, 3},
{"g14: half of 16 across 1 slot", 50, 16, 1, 800, 8},
{"one processor at least", 10, 2, 4, 100, 1},
{"no slots counts as one", 100, 4, 0, 400, 4},
{"a share out of range is the default", 0, 8, 1, 0, 4},
} {
t.Run(c.name, func(t *testing.T) {
p, err := Of(c.setting, c.node)
if c.refused {
if err == nil {
t.Fatalf("Of(%q) = %d, want refused", c.setting, p)
}
return
if c.quota != 0 {
if q := Quota(c.percent, c.cores); q != c.quota {
t.Errorf("%s: Quota = %d, want %d", c.name, q, c.quota)
}
if err != nil {
t.Fatal(err)
}
if p != c.percent {
t.Fatalf("percent = %d, want %d", p, c.percent)
}
if q := Quota(p, c.cores); q != c.quota {
t.Errorf("Quota = %d, want %d", q, c.quota)
}
if th := Threads(p, c.cores, c.slots); th != c.threads {
t.Errorf("Threads = %d, want %d", th, c.threads)
}
})
}
if th := Threads(c.percent, c.cores, c.slots); th != c.threads {
t.Errorf("%s: Threads = %d, want %d", c.name, th, c.threads)
}
}
caps, _ := Parse("ace=75,shanks=50%")
if got := Format(caps); got != "ace=75,shanks=50" {
t.Errorf("Format = %q", got)
words := map[string]string{ShareWord: "75", SlotsWord: "6"}
l := FromWords(func(k string) string { return words[k] }, 2)
if l.Percent != 75 || l.From != ShareWord || l.Slots != 6 || l.SlotsFrom != SlotsWord || l.Threads != Threads(75, runtime.NumCPU(), 6) {
t.Errorf("from the words: %+v", l)
}
if got := WithEnv([]string{"A=1", "GOMAXPROCS=24"}, 3); !reflect.DeepEqual(got, []string{"A=1", "GOMAXPROCS=3", "UV_THREADPOOL_SIZE=3"}) {
t.Errorf("WithEnv = %q", got)
// Told nothing (or nonsense), a module assumes every build seat beside it at its own capacity, at the default share.
words = map[string]string{ShareWord: "250", SlotsWord: "many"}
if l := FromWords(func(k string) string { return words[k] }, 3); l.Percent != DefaultPercent || l.Slots != 3*BuildSeats || l.From != "default" {
t.Errorf("without usable words: %+v", l)
}
if got := Env(0); !reflect.DeepEqual(got, []string{"GOMAXPROCS=1", "UV_THREADPOOL_SIZE=1"}) {
t.Errorf("Env = %q", got)
}
}
// What the kernel holds a process to is read from its cgroup and stat files, not assumed.
// What the kernel holds a process to is read from its unit's and its slice's cgroup and its stat file, not assumed.
func TestReadInForce(t *testing.T) {
dir := t.TempDir()
cg := filepath.Join(dir, "cg")
unit := filepath.Join(cg, "system.slice", "mesh-build-go-runtime.service")
slice := filepath.Join(cg, "meshyield.slice")
unit := filepath.Join(slice, "mesh-build-go-runtime.service")
if err := os.MkdirAll(unit, 0o755); err != nil {
t.Fatal(err)
}
for name, v := range map[string]string{"cpu.idle": "1\n", "cpu.weight": "0\n", "cpu.max": "1200000 100000\n", "io.weight": "default 1\n"} {
if err := os.WriteFile(filepath.Join(unit, name), []byte(v), 0o644); err != nil {
t.Fatal(err)
for at, files := range map[string]map[string]string{
slice: {"cpu.idle": "1\n", "cpu.weight": "0\n", "cpu.max": "1200000 100000\n", "io.weight": "default 1\n"},
unit: {"cpu.idle": "0\n", "cpu.weight": "100\n", "cpu.max": "max 100000\n", "io.weight": "default 100\n"},
} {
for name, v := range files {
if err := os.WriteFile(filepath.Join(at, name), []byte(v), 0o644); err != nil {
t.Fatal(err)
}
}
}
self := filepath.Join(dir, "cgroup")
stat := filepath.Join(dir, "stat")
_ = os.WriteFile(self, []byte("0::/system.slice/mesh-build-go-runtime.service\n"), 0o644)
_ = os.WriteFile(self, []byte("0::/meshyield.slice/mesh-build-go-runtime.service\n"), 0o644)
// A command with a space and a parenthesis in it, then nice 19 in field 19.
_ = os.WriteFile(stat, []byte("42 (mesh (build) go) S 1 42 42 0 -1 4194560 1 0 0 0 0 0 0 0 39 19 8 0 1 2 3\n"), 0o644)
cgroupRoot, procSelfCgroup, procSelfStat = cg, self, stat
@@ -83,12 +78,13 @@ func TestReadInForce(t *testing.T) {
})
got := ReadInForce()
want := InForce{Nice: 19, Cgroup: "/system.slice/mesh-build-go-runtime.service", CPUIdle: "1", CPUWeight: "0",
CPUMax: "1200000 100000", Quota: 1200, IOWeight: "default 1"}
want := InForce{Nice: 19, Cgroup: "/meshyield.slice/mesh-build-go-runtime.service",
Unit: Group{Path: "/meshyield.slice/mesh-build-go-runtime.service", CPUIdle: "0", CPUWeight: "100",
CPUMax: "max 100000", IOWeight: "default 100"},
Slice: Group{Path: "/meshyield.slice", CPUIdle: "1", CPUWeight: "0", CPUMax: "1200000 100000",
IOWeight: "default 1"},
Quota: 1200}
if !reflect.DeepEqual(got, want) {
t.Fatalf("ReadInForce = %+v\nwant %+v", got, want)
}
if q := quotaOf("max 100000"); q != 0 {
t.Errorf("no quota read as %d", q)
}
}