@smoothbricks/nx-plugin 0.7.17 → 0.7.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/README.md +315 -114
  2. package/dist/.build-inputs.json +47 -38
  3. package/dist/built-output-packages.js +1 -1
  4. package/dist/bun-lock-scope.d.ts +128 -20
  5. package/dist/bun-lock-scope.d.ts.map +1 -1
  6. package/dist/bun-lock-scope.js +267 -44
  7. package/dist/cargo-closure-input.d.ts +8 -6
  8. package/dist/cargo-closure-input.d.ts.map +1 -1
  9. package/dist/cargo-closure-input.js +15 -12
  10. package/dist/cargo-source-hash.d.ts +26 -25
  11. package/dist/cargo-source-hash.d.ts.map +1 -1
  12. package/dist/cargo-source-hash.js +84 -105
  13. package/dist/cargo-toolchain-paths.d.ts +2 -2
  14. package/dist/cargo-toolchain-paths.js +2 -2
  15. package/dist/cargo-workspace.d.ts +20 -2
  16. package/dist/cargo-workspace.d.ts.map +1 -1
  17. package/dist/cargo-workspace.js +43 -22
  18. package/dist/ensure-built-receipt.d.ts +3 -2
  19. package/dist/ensure-built-receipt.d.ts.map +1 -1
  20. package/dist/ensure-built-receipt.js +3 -2
  21. package/dist/eslint-config-closure.d.ts +8 -3
  22. package/dist/eslint-config-closure.d.ts.map +1 -1
  23. package/dist/eslint-config-closure.js +24 -5
  24. package/dist/executors/bounded-exec/admission-queue.d.ts +3 -1
  25. package/dist/executors/bounded-exec/admission-queue.d.ts.map +1 -1
  26. package/dist/executors/bounded-exec/admission-queue.js +9 -10
  27. package/dist/executors/bounded-exec/awake-clock.d.ts +5 -0
  28. package/dist/executors/bounded-exec/awake-clock.d.ts.map +1 -0
  29. package/dist/executors/bounded-exec/awake-clock.js +22 -0
  30. package/dist/executors/bounded-exec/bounds.d.ts +19 -6
  31. package/dist/executors/bounded-exec/bounds.d.ts.map +1 -1
  32. package/dist/executors/bounded-exec/bounds.js +22 -15
  33. package/dist/executors/bounded-exec/case-gate.d.ts +114 -0
  34. package/dist/executors/bounded-exec/case-gate.d.ts.map +1 -0
  35. package/dist/executors/bounded-exec/case-gate.js +342 -0
  36. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts +1 -0
  37. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts.map +1 -1
  38. package/dist/executors/bounded-exec/cpu-pool-thread.js +2 -2
  39. package/dist/executors/bounded-exec/cpu-pool.d.ts +28 -1
  40. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -1
  41. package/dist/executors/bounded-exec/cpu-pool.js +102 -16
  42. package/dist/executors/bounded-exec/cpu-rise.d.ts +73 -0
  43. package/dist/executors/bounded-exec/cpu-rise.d.ts.map +1 -0
  44. package/dist/executors/bounded-exec/cpu-rise.js +111 -0
  45. package/dist/executors/bounded-exec/endpoint-life.d.ts +146 -0
  46. package/dist/executors/bounded-exec/endpoint-life.d.ts.map +1 -0
  47. package/dist/executors/bounded-exec/endpoint-life.js +228 -0
  48. package/dist/executors/bounded-exec/executor.d.ts +1 -1
  49. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  50. package/dist/executors/bounded-exec/executor.js +256 -86
  51. package/dist/executors/bounded-exec/gateway-lease.d.ts +1 -1
  52. package/dist/executors/bounded-exec/gateway-lease.d.ts.map +1 -1
  53. package/dist/executors/bounded-exec/gateway-lease.js +8 -1
  54. package/dist/executors/bounded-exec/go-run-summary.d.ts +51 -0
  55. package/dist/executors/bounded-exec/go-run-summary.d.ts.map +1 -0
  56. package/dist/executors/bounded-exec/go-run-summary.js +98 -0
  57. package/dist/executors/bounded-exec/hang-diagnostics.d.ts +11 -3
  58. package/dist/executors/bounded-exec/hang-diagnostics.d.ts.map +1 -1
  59. package/dist/executors/bounded-exec/hang-diagnostics.js +125 -47
  60. package/dist/executors/bounded-exec/lease-wait.d.ts +1 -0
  61. package/dist/executors/bounded-exec/lease-wait.d.ts.map +1 -1
  62. package/dist/executors/bounded-exec/lease-wait.js +1 -0
  63. package/dist/executors/bounded-exec/mbx-pool.d.ts +42 -7
  64. package/dist/executors/bounded-exec/mbx-pool.d.ts.map +1 -1
  65. package/dist/executors/bounded-exec/mbx-pool.js +45 -8
  66. package/dist/executors/bounded-exec/mbx-reservations.d.ts +12 -6
  67. package/dist/executors/bounded-exec/mbx-reservations.d.ts.map +1 -1
  68. package/dist/executors/bounded-exec/mbx-reservations.js +190 -284
  69. package/dist/executors/bounded-exec/parent-grant.d.ts +2 -0
  70. package/dist/executors/bounded-exec/parent-grant.d.ts.map +1 -1
  71. package/dist/executors/bounded-exec/parent-grant.js +1 -0
  72. package/dist/executors/bounded-exec/pool-admission.d.ts +29 -3
  73. package/dist/executors/bounded-exec/pool-admission.d.ts.map +1 -1
  74. package/dist/executors/bounded-exec/pool-admission.js +47 -1
  75. package/dist/executors/bounded-exec/progress-channel.d.ts +38 -0
  76. package/dist/executors/bounded-exec/progress-channel.d.ts.map +1 -0
  77. package/dist/executors/bounded-exec/progress-channel.js +113 -0
  78. package/dist/executors/bounded-exec/progress.d.ts +5 -1
  79. package/dist/executors/bounded-exec/progress.d.ts.map +1 -1
  80. package/dist/executors/bounded-exec/progress.js +31 -1
  81. package/dist/executors/bounded-exec/ram-temp.d.ts +24 -1
  82. package/dist/executors/bounded-exec/ram-temp.d.ts.map +1 -1
  83. package/dist/executors/bounded-exec/ram-temp.js +123 -16
  84. package/dist/executors/bounded-exec/reservation-connection.d.ts +90 -0
  85. package/dist/executors/bounded-exec/reservation-connection.d.ts.map +1 -0
  86. package/dist/executors/bounded-exec/reservation-connection.js +248 -0
  87. package/dist/executors/bounded-exec/run-cpu-pool.d.ts.map +1 -1
  88. package/dist/executors/bounded-exec/run-cpu-pool.js +3 -0
  89. package/dist/executors/bounded-exec/runner-sizing.d.ts +9 -5
  90. package/dist/executors/bounded-exec/runner-sizing.d.ts.map +1 -1
  91. package/dist/executors/bounded-exec/runner-sizing.js +13 -9
  92. package/dist/executors/bounded-exec/schema.d.ts +7 -2
  93. package/dist/executors/bounded-exec/schema.d.ts.map +1 -1
  94. package/dist/executors/bounded-exec/schema.js +17 -1
  95. package/dist/executors/bounded-exec/suite-minimum.d.ts +21 -0
  96. package/dist/executors/bounded-exec/suite-minimum.d.ts.map +1 -0
  97. package/dist/executors/bounded-exec/suite-minimum.js +85 -0
  98. package/dist/executors/bounded-exec/test-result-writer.d.ts +2 -0
  99. package/dist/executors/bounded-exec/test-result-writer.d.ts.map +1 -1
  100. package/dist/executors/bounded-exec/test-result-writer.js +1 -0
  101. package/dist/executors/bounded-exec/test-results.d.ts +5 -0
  102. package/dist/executors/bounded-exec/test-results.d.ts.map +1 -1
  103. package/dist/executors/bounded-exec/test-results.js +2 -2
  104. package/dist/executors/bounded-exec/verdict.d.ts +39 -10
  105. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  106. package/dist/executors/bounded-exec/verdict.js +60 -14
  107. package/dist/executors/cargo-zigbuild/executor.d.ts +10 -8
  108. package/dist/executors/cargo-zigbuild/executor.d.ts.map +1 -1
  109. package/dist/executors/cargo-zigbuild/executor.js +32 -19
  110. package/dist/index.d.ts.map +1 -1
  111. package/dist/index.js +294 -152
  112. package/dist/managed-files/ci-workflow.d.ts +4 -1
  113. package/dist/managed-files/ci-workflow.d.ts.map +1 -1
  114. package/dist/managed-files/ci-workflow.js +9 -14
  115. package/dist/managed-files/files.d.ts +3 -3
  116. package/dist/managed-files/files.js +3 -3
  117. package/dist/managed-files/generator.d.ts +5 -1
  118. package/dist/managed-files/generator.d.ts.map +1 -1
  119. package/dist/managed-files/generator.js +22 -7
  120. package/dist/managed-files/render-memo.d.ts +13 -0
  121. package/dist/managed-files/render-memo.d.ts.map +1 -0
  122. package/dist/managed-files/render-memo.js +94 -0
  123. package/dist/task-results.js +2 -1
  124. package/dist/test-program.d.ts +11 -6
  125. package/dist/test-program.d.ts.map +1 -1
  126. package/dist/test-program.js +39 -35
  127. package/dist/tool-bins.d.ts +12 -0
  128. package/dist/tool-bins.d.ts.map +1 -1
  129. package/dist/tool-bins.js +31 -6
  130. package/dist/typecheck-test-policy.d.ts +10 -1
  131. package/dist/typecheck-test-policy.d.ts.map +1 -1
  132. package/dist/typecheck-test-policy.js +40 -24
  133. package/dist/workspace-config-policy.d.ts.map +1 -1
  134. package/dist/workspace-config-policy.js +135 -42
  135. package/dist/workspace-index.d.ts +14 -1
  136. package/dist/workspace-index.d.ts.map +1 -1
  137. package/dist/workspace-index.js +36 -4
  138. package/executors.json +2 -0
  139. package/managed/raw/envrc +24 -0
  140. package/managed/raw/patches/nx@24.0.3.patch +1851 -221
  141. package/managed/raw/patches/ttsc@0.37.1.patch +1055 -0
  142. package/managed/raw/tooling/direnv/developer-links.ts +122 -14
  143. package/managed/raw/tooling/direnv/devenv.smoo.nix +20 -19
  144. package/managed/templates/github/actions/save-nix-devenv/action.yml +19 -1
  145. package/managed/templates/github/actions/setup-devenv/action.yml +2 -0
  146. package/package.json +68 -11
  147. package/runtime/nx-publish/.build-inputs.json +2 -2
  148. package/runtime/nx-publish/cache_adapter.js +293 -3
  149. package/runtime/nx-publish/nx_publish.js +36 -14
  150. package/src/built-output-packages.ts +1 -1
  151. package/src/bun-lock-scope.ts +293 -40
  152. package/src/cargo-closure-input.ts +20 -12
  153. package/src/cargo-source-hash.ts +119 -145
  154. package/src/cargo-toolchain-paths.ts +2 -2
  155. package/src/cargo-workspace.ts +59 -21
  156. package/src/ensure-built-receipt.ts +3 -2
  157. package/src/eslint-config-closure.ts +27 -6
  158. package/src/executors/bounded-exec/admission-queue.ts +11 -10
  159. package/src/executors/bounded-exec/awake-clock.ts +20 -0
  160. package/src/executors/bounded-exec/bounds.ts +41 -19
  161. package/src/executors/bounded-exec/case-gate.ts +365 -0
  162. package/src/executors/bounded-exec/cpu-pool-thread.ts +3 -3
  163. package/src/executors/bounded-exec/cpu-pool.ts +139 -12
  164. package/src/executors/bounded-exec/cpu-rise.ts +156 -0
  165. package/src/executors/bounded-exec/endpoint-life.ts +279 -0
  166. package/src/executors/bounded-exec/executor.ts +341 -123
  167. package/src/executors/bounded-exec/gateway-lease.ts +6 -0
  168. package/src/executors/bounded-exec/go-run-summary.ts +137 -0
  169. package/src/executors/bounded-exec/hang-diagnostics.ts +150 -50
  170. package/src/executors/bounded-exec/lease-wait.ts +1 -0
  171. package/src/executors/bounded-exec/mbx-pool.ts +57 -9
  172. package/src/executors/bounded-exec/mbx-reservations.ts +216 -183
  173. package/src/executors/bounded-exec/parent-grant.ts +3 -0
  174. package/src/executors/bounded-exec/pool-admission.ts +59 -2
  175. package/src/executors/bounded-exec/progress-channel.ts +129 -0
  176. package/src/executors/bounded-exec/progress.ts +39 -3
  177. package/src/executors/bounded-exec/ram-temp.ts +137 -17
  178. package/src/executors/bounded-exec/reservation-connection.ts +221 -0
  179. package/src/executors/bounded-exec/run-cpu-pool.ts +2 -0
  180. package/src/executors/bounded-exec/runner-sizing.ts +13 -8
  181. package/src/executors/bounded-exec/schema.json +1 -1
  182. package/src/executors/bounded-exec/schema.ts +21 -2
  183. package/src/executors/bounded-exec/suite-minimum.ts +81 -0
  184. package/src/executors/bounded-exec/test-result-writer.ts +3 -0
  185. package/src/executors/bounded-exec/test-results.ts +5 -0
  186. package/src/executors/bounded-exec/verdict.ts +83 -22
  187. package/src/executors/cargo-zigbuild/executor.ts +30 -19
  188. package/src/index.ts +357 -166
  189. package/src/managed-files/ci-workflow.ts +13 -17
  190. package/src/managed-files/files.ts +3 -3
  191. package/src/managed-files/generator.ts +21 -6
  192. package/src/managed-files/render-memo.ts +135 -0
  193. package/src/test-program.ts +36 -41
  194. package/src/tool-bins.ts +35 -6
  195. package/src/typecheck-test-policy.ts +49 -24
  196. package/src/workspace-config-policy.ts +161 -43
  197. package/src/workspace-index.ts +40 -5
  198. package/test-timings.json +157 -141
  199. package/managed/raw/patches/ttsc@0.36.3.patch +0 -1660
@@ -6,10 +6,11 @@ import { join } from 'node:path';
6
6
  import { promisify } from 'node:util';
7
7
  import typia from 'typia';
8
8
  import { ownedSocketDirectory } from '../../testing.js';
9
+ import type { CaseCore } from './case-gate.js';
9
10
  import { holdLease, type Unleased } from './gateway-lease.js';
10
11
  import { type LiveUsageReading, type RunMemory, readLiveUsage } from './host-memory.js';
11
12
  import { type CpuLeaseProgress, type CpuLeaseQueued, CpuLeaseWait, HEARTBEAT_MS } from './lease-wait.js';
12
- import { admit } from './pool-admission.js';
13
+ import { admit, IdleBesideStarved, place } from './pool-admission.js';
13
14
  import { type InheritedCpuPool, poolEnvironment } from './pool-environment.js';
14
15
 
15
16
  /**
@@ -50,6 +51,36 @@ export interface CpuPool {
50
51
  close(): Promise<CloseOutcome>;
51
52
  }
52
53
 
54
+ /** What a pool says when it closes: the token-time idle beside starved holds, and the grants that made them. */
55
+ export interface PoolSummary {
56
+ /** Token-milliseconds no socket grant held while a hold was starved (pool-admission.ts, `IdleBesideStarved`). */
57
+ readonly idleBesideStarvedMs: number;
58
+ /** Leaves granted fewer tokens than they asked, whether gated or not. */
59
+ readonly starved: number;
60
+ /** Lent tokens granted, one per test case. */
61
+ readonly lent: number;
62
+ }
63
+
64
+ /** When a pool lends: its clock, and how long after a leaf's grant returns it grants no lent request. */
65
+ export interface Lending {
66
+ readonly settleMs: number;
67
+ readonly now: () => number;
68
+ }
69
+
70
+ /**
71
+ * The settle time (specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets itself"): Nx starts a run's next
72
+ * task when one ends, and that task's leaf takes what its predecessor freed before any case is lent it.
73
+ */
74
+ const LEND_SETTLE_MS = 3_000;
75
+ const LENDING: Lending = { settleMs: LEND_SETTLE_MS, now: () => performance.now() };
76
+
77
+ /** The line a run's pool says of `summary` when it closes; null for a pool that starved no leaf and lent nothing. */
78
+ export function describeIdle(summary: PoolSummary): string | null {
79
+ return summary.starved === 0 && summary.lent === 0
80
+ ? null
81
+ : `cowshed: cpu-pool idle beside_starved_core_s=${(summary.idleBesideStarvedMs / 1000).toFixed(3)} starved=${summary.starved} lent=${summary.lent}\n`;
82
+ }
83
+
53
84
  export type CloseOutcome = { ok: true } | { ok: false; error: string };
54
85
 
55
86
  /**
@@ -64,6 +95,12 @@ interface CpuPoolRequest {
64
95
  parallelism?: number & typia.tags.Type<'uint32'> & typia.tags.Minimum<1>;
65
96
  task?: string & typia.tags.MaxLength<256>;
66
97
  alone?: boolean;
98
+ /** One token for one test case of a leaf that holds a grant: granted only while no other request waits. */
99
+ lend?: boolean;
100
+ /** A lent request's leaf's predicted work left, in ms. */
101
+ left?: number & typia.tags.Type<'uint64'>;
102
+ /** A leaf whose cases each ask for a token of their own (`lend`): what it lacks of its ask is not idle beside it. */
103
+ gated?: boolean;
67
104
  }
68
105
 
69
106
  /** A grant whose charge alone exceeds the run's memory, made while nothing else held memory: the run's memory. */
@@ -110,6 +147,9 @@ type Phase =
110
147
  readonly slot: boolean;
111
148
  readonly memory: number;
112
149
  readonly alone: boolean;
150
+ readonly tokens: number;
151
+ readonly starved: boolean;
152
+ readonly lend: boolean;
113
153
  }
114
154
  | { readonly kind: 'done' };
115
155
 
@@ -127,6 +167,9 @@ interface Waiter {
127
167
  readonly parallelism?: number | undefined;
128
168
  readonly task?: string | undefined;
129
169
  readonly alone?: boolean | undefined;
170
+ readonly lend?: boolean | undefined;
171
+ readonly left?: number | undefined;
172
+ readonly gated?: boolean | undefined;
130
173
  }
131
174
 
132
175
  /** One framed reply line. The newline is the framing; every reply goes through here. */
@@ -159,6 +202,8 @@ export interface AskContext {
159
202
  readonly task?: string | undefined;
160
203
  /** The kernel killed the command for memory: it is run again, granted only while nothing else holds a grant. */
161
204
  readonly alone?: boolean | undefined;
205
+ /** Its cases each ask the pool for a token of their own. */
206
+ readonly gated?: boolean | undefined;
162
207
  }
163
208
 
164
209
  /**
@@ -176,7 +221,7 @@ export async function takeParentCpuTokens(
176
221
  memory: number | null,
177
222
  context: AskContext = {},
178
223
  ): Promise<TokenGrant> {
179
- const { parallelism, task, alone } = context;
224
+ const { parallelism, task, alone, gated } = context;
180
225
  if (!Number.isSafeInteger(want) || want < 1) {
181
226
  throw new RangeError(`a child asks its parent pool for a positive count, not ${want} (pool ${parent.tokens})`);
182
227
  }
@@ -199,6 +244,7 @@ export async function takeParentCpuTokens(
199
244
  ...(memory === null ? {} : { memory, ...(parallelism === undefined ? {} : { parallelism }) }),
200
245
  ...(task === undefined ? {} : { task }),
201
246
  ...(alone === true ? { alone: true } : {}),
247
+ ...(gated === true ? { gated: true } : {}),
202
248
  };
203
249
  const lease = await holdLease(parent.socket, request, 'the parent CPU pool', new CpuLeaseWait());
204
250
  if (!lease.granted) {
@@ -239,6 +285,38 @@ export async function takeParentCpuTokens(
239
285
  };
240
286
  }
241
287
 
288
+ /**
289
+ * One token of `parent` asked for one test case of a leaf that holds a grant of it, named `task` in the request
290
+ * (specs/cowshed/05_gateway.md, "A case starts on a core", Inside a hold). The pool grants it only while no other
291
+ * request waits. `release` gives the token back, or withdraws the request while it waits. A pool that refuses, falls
292
+ * silent or is gone grants nothing: the case waits for a token of its leaf's own grant.
293
+ */
294
+ export function lendParentToken(parent: InheritedCpuPool, task: string, left: number): CaseCore {
295
+ const withdrawn = new AbortController();
296
+ const lease = holdLease(
297
+ parent.socket,
298
+ { op: 'cpu-pool', want: 1, lend: true, left: Math.max(0, Math.round(left)), task: task.slice(0, MAX_TASK_LENGTH) },
299
+ 'the parent CPU pool',
300
+ new CpuLeaseWait(),
301
+ undefined,
302
+ withdrawn.signal,
303
+ );
304
+ let released = false;
305
+ return {
306
+ granted: lease.then((held) => held.granted && !released),
307
+ release: () => {
308
+ if (released) return;
309
+ released = true;
310
+ withdrawn.abort();
311
+ void lease.then((held) => {
312
+ if (held.granted) held.release();
313
+ });
314
+ },
315
+ };
316
+ }
317
+
318
+ /** A request's `task` is at most this long (`CpuPoolRequest`). */
319
+ const MAX_TASK_LENGTH = 256;
242
320
  /** A thrown value's message. */
243
321
  const describe = (error: unknown): string => (error instanceof Error ? error.message : String(error));
244
322
 
@@ -399,7 +477,8 @@ export async function createCpuPool(
399
477
  closed: Promise<void>,
400
478
  memory: RunMemory | null,
401
479
  liveUsage: (bound: string) => LiveUsageReading = readLiveUsage,
402
- ): Promise<{ ok: true; pool: CpuPool } | { ok: false; error: string }> {
480
+ lending: Lending = LENDING,
481
+ ): Promise<{ ok: true; pool: CpuPool; summary: () => PoolSummary } | { ok: false; error: string }> {
403
482
  if (!Number.isSafeInteger(tokens) || tokens < 1) {
404
483
  throw new RangeError(`a CPU pool holds a positive safe integer of tokens, not ${tokens}`);
405
484
  }
@@ -430,6 +509,15 @@ export async function createCpuPool(
430
509
  // The children holding a grant, and whether one of them runs alone.
431
510
  let holders = 0;
432
511
  let aloneHolder = false;
512
+ // The tokens socket grants hold, the leaves that hold fewer than they asked and take no gate, and what the pool says
513
+ // of both when it closes.
514
+ let heldTokens = 0;
515
+ let starvedHolders = 0;
516
+ let partialGrants = 0;
517
+ let lentGrants = 0;
518
+ const idle = new IdleBesideStarved(lending.now());
519
+ // A leaf return arms this one-shot window. A later leaf return replaces it; a case return does not.
520
+ let settle: NodeJS.Timeout | undefined;
433
521
  // The readability wait while the queue's head finds no token, else undefined.
434
522
  let watch: FifoWatch | undefined;
435
523
  let closing = false;
@@ -520,6 +608,7 @@ export async function createCpuPool(
520
608
  inHand + (slotLent ? 0 : 1),
521
609
  memory === null ? null : { capacity: memory.bytes, held: heldMemory },
522
610
  { holders, alone: aloneHolder },
611
+ settle === undefined,
523
612
  );
524
613
  queue.splice(0, admission.grants.length);
525
614
  for (const { request, tokens: granted, charge, oversized } of admission.grants) {
@@ -530,8 +619,23 @@ export async function createCpuPool(
530
619
  if (slot) slotLent = true;
531
620
  heldMemory += charge;
532
621
  holders += 1;
622
+ heldTokens += granted;
623
+ const partial = granted < request.want;
624
+ const starved = partial && request.gated !== true;
625
+ if (partial) partialGrants += 1;
626
+ if (starved) starvedHolders += 1;
627
+ if (request.lend === true) lentGrants += 1;
533
628
  if (request.alone === true) aloneHolder = true;
534
- request.child.phase = { kind: 'holding', bytes, slot, memory: charge, alone: request.alone === true };
629
+ request.child.phase = {
630
+ kind: 'holding',
631
+ bytes,
632
+ slot,
633
+ memory: charge,
634
+ alone: request.alone === true,
635
+ tokens: granted,
636
+ starved,
637
+ lend: request.lend === true,
638
+ };
535
639
  request.child.socket.write(
536
640
  frame(
537
641
  memory === null
@@ -542,7 +646,7 @@ export async function createCpuPool(
542
646
  ),
543
647
  );
544
648
 
545
- if (memory !== null) {
649
+ if (memory !== null && request.lend !== true) {
546
650
  const live = liveUsage(memory.source);
547
651
  const held = live.ok
548
652
  ? `${live.usage.anon + live.usage.shmem} bytes (anon ${live.usage.anon}, shmem ${live.usage.shmem}, ${live.usage.source})`
@@ -558,6 +662,7 @@ export async function createCpuPool(
558
662
  stopWatching();
559
663
  }
560
664
  returnTokens(inHand);
665
+ idle.observe(lending.now(), tokens - heldTokens, starvedHolders > 0 || queue.at(-1)?.lend === true);
561
666
  }
562
667
 
563
668
  const refuse = (child: Child, error: string): void => {
@@ -587,6 +692,17 @@ export async function createCpuPool(
587
692
  if (child.phase.slot) slotLent = false;
588
693
  heldMemory -= child.phase.memory;
589
694
  holders -= 1;
695
+ heldTokens -= child.phase.tokens;
696
+ if (child.phase.starved) starvedHolders -= 1;
697
+ // What a leaf returns is its successor's first: Nx starts the run's next task as this one ends.
698
+ if (!closing && !child.phase.lend && lending.settleMs > 0) {
699
+ clearTimeout(settle);
700
+ settle = setTimeout(() => {
701
+ settle = undefined;
702
+ drain(0);
703
+ }, lending.settleMs);
704
+ settle.unref();
705
+ }
590
706
  if (child.phase.alone) aloneHolder = false;
591
707
  if (!closing) returnTokens(child.phase.bytes);
592
708
  }
@@ -646,6 +762,13 @@ export async function createCpuPool(
646
762
  );
647
763
  return;
648
764
  }
765
+ if (parsed.lend === true && (parsed.want !== 1 || parsed.memory !== undefined || parsed.alone === true)) {
766
+ refuse(
767
+ child,
768
+ 'a lent request is one token for one test case: {"op":"cpu-pool","want":1,"lend":true,"task"?:<its case>}',
769
+ );
770
+ return;
771
+ }
649
772
  const request = parsed;
650
773
  child.phase = { kind: 'queued' };
651
774
  const waiter: Waiter = {
@@ -655,14 +778,11 @@ export async function createCpuPool(
655
778
  parallelism: request.parallelism,
656
779
  task: request.task,
657
780
  alone: request.alone,
781
+ lend: request.lend,
782
+ left: request.left,
783
+ gated: request.gated,
658
784
  };
659
- if (request.alone === true) {
660
- // A leaf the kernel killed has waited once already: it goes ahead of the leaves that have not run.
661
- const at = queue.findIndex((waiting) => waiting.alone !== true);
662
- queue.splice(at === -1 ? queue.length : at, 0, waiter);
663
- } else {
664
- queue.push(waiter);
665
- }
785
+ queue.splice(place(queue, waiter), 0, waiter);
666
786
  socket.write(frame({ ok: true, lease: 'queued', server: process.pid }));
667
787
  drain(0);
668
788
  });
@@ -676,6 +796,8 @@ export async function createCpuPool(
676
796
  shut ??= (async (): Promise<CloseOutcome> => {
677
797
  closing = true;
678
798
  clearInterval(heartbeat);
799
+ clearTimeout(settle);
800
+ idle.observe(lending.now(), 0, false);
679
801
  stopWatching();
680
802
  await started;
681
803
  for (const socket of children) {
@@ -773,5 +895,10 @@ export async function createCpuPool(
773
895
  environment: poolEnvironment(socketPath, tokens, fifoPath),
774
896
  close: shutdown,
775
897
  },
898
+ summary: () => ({
899
+ idleBesideStarvedMs: idle.tokenMs(lending.now()),
900
+ starved: partialGrants,
901
+ lent: lentGrants,
902
+ }),
776
903
  };
777
904
  }
@@ -0,0 +1,156 @@
1
+ import type { tags } from 'typia';
2
+
3
+ /**
4
+ * The CPU a run's tree used while its idle bound counted down. A test that runs a compiler is a build inside the test,
5
+ * which is a defect and not a test (specs/cowshed/08_testing.md, "Integration tests (real substrate)"): the pre-signal
6
+ * snapshot names the processes whose CPU time rose between its two process censuses, so the expiry fails as that and
7
+ * not as an anonymous hang. CPU never restarts the idle bound, which counts only finished tests and the progress a
8
+ * running test reports (progress-channel.ts); this says what ran.
9
+ */
10
+
11
+ /** What a rising process makes of the expiry, said in the same words by the snapshot and by the verdict. */
12
+ export const CPU_RISING_CLASS = "a process in the test's tree was using CPU: likely a build inside the test";
13
+
14
+ /**
15
+ * The least gain that names a rise, whatever resolution ps prints CPU time at: 10% of a core over the snapshot's five
16
+ * seconds between censuses.
17
+ */
18
+ export const CPU_RISE_FLOOR_MS = 500;
19
+
20
+ /**
21
+ * What a printed CPU time resolves to, in milliseconds: the value of its last digit. Whole seconds are 1,000, a
22
+ * fraction of n digits is 10^(3-n); a finer fraction is kept to the millisecond, so none is below 1.
23
+ */
24
+ export type CpuResolutionMs = 1_000 | 100 | 10 | 1;
25
+
26
+ /** A CPU time ps printed, with the resolution it was printed at. */
27
+ export interface CpuTime {
28
+ readonly ms: number;
29
+ readonly resolutionMs: CpuResolutionMs;
30
+ }
31
+
32
+ /** The longest command a rise keeps: a compiler's argument list runs to kilobytes, and its name leads it. */
33
+ const COMMAND_CHARS = 160;
34
+
35
+ /** A process whose CPU time rose between the snapshot's two censuses. */
36
+ export interface CpuRise {
37
+ readonly pid: number & tags.Type<'uint32'> & tags.Minimum<1>;
38
+ readonly command: string;
39
+ readonly gainedMs: number & tags.Minimum<0>;
40
+ }
41
+
42
+ /** One process of a census, as far as CPU is concerned. */
43
+ export interface CpuSample {
44
+ readonly pid: number;
45
+ readonly started: string;
46
+ readonly command: string;
47
+ /** Null when ps printed a CPU time that does not parse. */
48
+ readonly cpu: CpuTime | null;
49
+ }
50
+
51
+ export interface CpuChange {
52
+ /** Largest gain first. */
53
+ readonly rising: readonly CpuRise[];
54
+ /** Processes in both censuses that one of them gave no readable CPU time for: not counted idle. */
55
+ readonly unread: readonly number[];
56
+ }
57
+
58
+ function resolutionOfFraction(digits: number): CpuResolutionMs {
59
+ switch (digits) {
60
+ case 0:
61
+ return 1_000;
62
+ case 1:
63
+ return 100;
64
+ case 2:
65
+ return 10;
66
+ default:
67
+ return 1;
68
+ }
69
+ }
70
+
71
+ /**
72
+ * A ps CPU time (`cputime=`): `[[D-]HH:]MM:SS` with an optional fraction, as Linux prints it (whole seconds) and macOS
73
+ * does (centiseconds). Null for anything else, such as the `-` ps prints for a process it may not read.
74
+ */
75
+ export function parseCpuTime(text: string): CpuTime | null {
76
+ const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.(\d+))?)$/.exec(text);
77
+ if (match === null) return null;
78
+ const [, days, hours, minutes, seconds, fraction] = match;
79
+ if (minutes === undefined || seconds === undefined) return null;
80
+ const wholeMinutes = ((Number(days ?? 0) * 24 + Number(hours ?? 0)) * 60 + Number(minutes)) * 60;
81
+ return {
82
+ ms: Math.round((wholeMinutes + Number(seconds)) * 1_000),
83
+ resolutionMs: resolutionOfFraction(fraction?.length ?? 0),
84
+ };
85
+ }
86
+
87
+ /**
88
+ * The least gain between two readings of one process that names a rise: twice the coarser of their resolutions, and
89
+ * never under {@link CPU_RISE_FLOOR_MS}. A process that crossed a boundary of the last printed digit on a few
90
+ * milliseconds of work gains one resolution, so two are more than one. That is 2,000 ms between whole-second readings
91
+ * and 500 ms between centisecond ones.
92
+ */
93
+ export function cpuRiseThresholdMs(before: CpuTime, after: CpuTime): number {
94
+ return Math.max(CPU_RISE_FLOOR_MS, 2 * Math.max(before.resolutionMs, after.resolutionMs));
95
+ }
96
+
97
+ /** Each process present in both censuses (same pid and start), as its earlier and its later sample. */
98
+ function paired(before: readonly CpuSample[], after: readonly CpuSample[]): (readonly [CpuSample, CpuSample])[] {
99
+ const earlier = new Map(before.map((sample) => [`${sample.pid} ${sample.started}`, sample]));
100
+ const pairs: (readonly [CpuSample, CpuSample])[] = [];
101
+ for (const sample of after) {
102
+ const first = earlier.get(`${sample.pid} ${sample.started}`);
103
+ if (first !== undefined) pairs.push([first, sample]);
104
+ }
105
+ return pairs;
106
+ }
107
+
108
+ /**
109
+ * The processes present in both censuses (same pid and start) whose CPU time rose by at least
110
+ * {@link cpuRiseThresholdMs}.
111
+ */
112
+ export function cpuChange(before: readonly CpuSample[], after: readonly CpuSample[]): CpuChange {
113
+ const rising: CpuRise[] = [];
114
+ const unread: number[] = [];
115
+ for (const [first, sample] of paired(before, after)) {
116
+ if (first.cpu === null || sample.cpu === null) {
117
+ unread.push(sample.pid);
118
+ continue;
119
+ }
120
+ const gainedMs = sample.cpu.ms - first.cpu.ms;
121
+ if (gainedMs < cpuRiseThresholdMs(first.cpu, sample.cpu)) continue;
122
+ const command =
123
+ sample.command.length > COMMAND_CHARS ? `${sample.command.slice(0, COMMAND_CHARS)}…` : sample.command;
124
+ rising.push({ pid: sample.pid, command, gainedMs });
125
+ }
126
+ rising.sort((a, b) => b.gainedMs - a.gainedMs || a.pid - b.pid);
127
+ return { rising, unread };
128
+ }
129
+
130
+ /**
131
+ * The gains {@link cpuChange} held these censuses to, each distinct one once, smallest first: one per resolution of the
132
+ * readings compared, and none when no process had a readable CPU time in both.
133
+ */
134
+ export function cpuRiseThresholdsMs(before: readonly CpuSample[], after: readonly CpuSample[]): readonly number[] {
135
+ const thresholds = new Set<number>();
136
+ for (const [first, sample] of paired(before, after)) {
137
+ if (first.cpu !== null && sample.cpu !== null) thresholds.add(cpuRiseThresholdMs(first.cpu, sample.cpu));
138
+ }
139
+ return [...thresholds].sort((a, b) => a - b);
140
+ }
141
+
142
+ /** The gains of {@link cpuRiseThresholdsMs} in seconds, as the snapshot says them: `2 s`, or `0.5 s or 2 s`. */
143
+ export function describeCpuThresholds(thresholdsMs: readonly number[]): string {
144
+ return thresholdsMs.map((ms) => `${ms / 1_000} s`).join(' or ');
145
+ }
146
+
147
+ export function describeCpuRise(rise: CpuRise): string {
148
+ return `pid ${rise.pid} (${rise.command}) gained ${(rise.gainedMs / 1_000).toFixed(1)} s of CPU`;
149
+ }
150
+
151
+ /** The largest gains, named, and how many more there were: a parallel build runs many processes. */
152
+ export function describeCpuRises(rises: readonly CpuRise[], named = 3): string {
153
+ const shown = rises.slice(0, named).map(describeCpuRise);
154
+ const more = rises.length - shown.length;
155
+ return `${shown.join('; ')}${more > 0 ? `; and ${more} more` : ''}`;
156
+ }