nx_shipfleet_lib.nx source
↩ module page · 57 lines · 2933 B
1// nx_shipfleet_lib.nx -- the PURE decision core for INTELLIGENT (adaptive-concurrency) shipping.
2// Composes the estate's polite headroom budget (nx_resource_governor rg_worker_budget/rg_hw_budget) with
3// an AIMD cap that responds to the DIRECT I/O-storm signal (nx_build_admit's exit code), so a fleet of
4// ships runs as WIDE as the box allows RIGHT NOW and no wider: additive-increase +1 on progress,
5// multiplicative-decrease (halve) on a storm refusal. This is TCP congestion control applied to build
6// admission -- the field infers congestion from latency (minRTT/RTT gradient, Netflix concurrency-limits,
7// Envoy adaptive_concurrency, ThomWright/congestion-limiter); OUR exceed is that the signal is MEASURED,
8// not inferred -- nx_build_admit reads /proc D-state directly. Pure policy: host signals passed in, no
9// syscalls, so the gate can bite-prove the whole state machine. license_tier: ORIGINAL
10
11const SF_OK: i64 = 0 // progress this tick (a ship launched / the box granted) -> room to grow
12const SF_STORM: i64 = 1 // build admission refused (I/O storm / no headroom) -> back off hard
13const SF_HOLD: i64 = 2 // neither -> leave the cap where it is (only clamp to ceiling)
14
15// AIMD step on the concurrency cap. ceil is the polite headroom budget (rg_worker_budget); the cap NEVER
16// exceeds it (politeness is the hard ceiling) and NEVER drops below 1 (a 0-cap fleet is a dead feature --
17// pausing is the effective-width gate's job, not the cap's). +1 on OK, halve on STORM, clamp on HOLD.
18func sf_aimd_next(cap: i64, ceil: i64, event: i64) -> i64 {
19 var c: i64 = cap
20 if c < 1 { c = 1 }
21 var top: i64 = ceil
22 if top < 1 { top = 1 }
23 if event == SF_STORM {
24 c = c / 2
25 if c < 1 { c = 1 }
26 return c
27 }
28 if event == SF_OK {
29 c = c + 1
30 if c > top { c = top }
31 return c
32 }
33 // SF_HOLD (or any unknown event): keep the cap, only enforce the ceiling.
34 if c > top { c = top }
35 return c
36}
37
38// The width to run THIS tick. 0 = PAUSE entirely (fork nothing this beat):
39// - hosting is serving live visitors (serve_first) -> QoS is sacred, background work yields; OR
40// - the box refused admission (admit_grant != 1) -> the I/O storm / no-headroom signal.
41// Otherwise the SMALLER of the polite budget and the AIMD cap. Never negative.
42func sf_effective_width(rg_budget: i64, aimd_cap: i64, admit_grant: i64, serve_first: i64) -> i64 {
43 if serve_first == 1 { return 0 }
44 if admit_grant != 1 { return 0 }
45 var w: i64 = rg_budget
46 if aimd_cap < w { w = aimd_cap }
47 if w < 0 { w = 0 }
48 return w
49}
50
51// How many MORE ships to launch this tick, given the effective width and how many are already in flight.
52// Never negative; a width at or below in_flight means "hold, reap first".
53func sf_launch_slots(width: i64, in_flight: i64) -> i64 {
54 let s: i64 = width - in_flight
55 if s < 0 { return 0 }
56 return s
57}