mandrel 2.84.0 → 2.86.0

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.
@@ -12,6 +12,12 @@ import {
12
12
  isHolderAlive,
13
13
  readLockHolderPid,
14
14
  } from './single-story-sweep/sweep-lock.js';
15
+ import {
16
+ admissionWaitLine,
17
+ admittedLine,
18
+ blockingLabel,
19
+ publicBlocking,
20
+ } from './suite-admission.js';
15
21
 
16
22
  const LOCK_TAG = '[full-suite-lock]';
17
23
 
@@ -94,20 +100,8 @@ function isLiveEntry({ dir, name, staleMs, nowFn, fsImpl, killFn }) {
94
100
  }
95
101
  }
96
102
 
97
- /**
98
- * With no ticket, true only when nobody is queued.
99
- *
100
- * @param {{
101
- * lockPath: string,
102
- * ticket: Ticket|null,
103
- * staleMs: number,
104
- * nowFn?: () => number,
105
- * fsImpl?: object,
106
- * killFn?: Function,
107
- * }} opts
108
- * @returns {boolean}
109
- */
110
- export function isFirstInLine({
103
+ /** Live waiters ahead of `ticket`; `null` when the queue is unreadable. */
104
+ function countAhead({
111
105
  lockPath,
112
106
  ticket,
113
107
  staleMs,
@@ -120,15 +114,31 @@ export function isFirstInLine({
120
114
  try {
121
115
  names = fsImpl.readdirSync(dir).map(String).sort();
122
116
  } catch {
123
- return true;
124
- }
125
- for (const name of names) {
126
- if (name === ticket?.name) return true;
127
- if (isLiveEntry({ dir, name, staleMs, nowFn, fsImpl, killFn })) {
128
- return false;
129
- }
117
+ return null;
130
118
  }
131
- return true;
119
+ const own = ticket ? names.indexOf(ticket.name) : -1;
120
+ return names
121
+ .slice(0, own === -1 ? names.length : own)
122
+ .filter((name) =>
123
+ isLiveEntry({ dir, name, staleMs, nowFn, fsImpl, killFn }),
124
+ ).length;
125
+ }
126
+
127
+ /**
128
+ * With no ticket, true only when nobody is queued.
129
+ *
130
+ * @param {{
131
+ * lockPath: string,
132
+ * ticket: Ticket|null,
133
+ * staleMs: number,
134
+ * nowFn?: () => number,
135
+ * fsImpl?: object,
136
+ * killFn?: Function,
137
+ * }} opts
138
+ * @returns {boolean}
139
+ */
140
+ export function isFirstInLine(opts) {
141
+ return (countAhead(opts) ?? 0) === 0;
132
142
  }
133
143
 
134
144
  /**
@@ -171,19 +181,32 @@ function holderLabel(lockPath, fsImpl) {
171
181
  return `holding pid ${readLockHolderPid(lockPath, fsImpl) ?? 'unknown'}`;
172
182
  }
173
183
 
184
+ /**
185
+ * @typedef {{
186
+ * phase: 'waiting'|'still-waiting'|'admitted'|'completed'|'expired',
187
+ * waitedSeconds: number, waitBudgetSeconds: number,
188
+ * holder?: LockHolder, queueAhead?: number, blocking?: object,
189
+ * waitMs?: number, executionMs?: number,
190
+ * }} LockProgress
191
+ */
192
+
174
193
  /**
175
194
  * @param {{
176
195
  * lockPath: string, waitMs: number, pollMs: number, staleMs: number,
177
196
  * reportMs: number, fsImpl: object, nowFn: () => number,
178
- * sleepFn: (ms: number) => Promise<void>, acquireOnceFn: Function,
197
+ * sleepFn: (ms: number) => Promise<void>,
198
+ * attempt: { tryOnce: () => object }, workload?: object,
179
199
  * log: (m: string) => void, rerunCommand: string,
180
- * }} opts
200
+ * onLockProgress?: (progress: LockProgress) => void,
201
+ * }} opts A throwing `onLockProgress` is swallowed.
181
202
  * @returns {Promise<{ held: object|null, expired: boolean, waited: true, waitedMs: number, holder?: LockHolder }>}
182
203
  */
183
204
  export async function waitInLine(opts) {
184
205
  const { lockPath, fsImpl, nowFn } = opts;
185
206
  const clock = waitClock(opts);
207
+ clock.blocking = opts.blocking ?? null;
186
208
  announceWait(opts);
209
+ reportProgress(opts, clock, 'waiting', null);
187
210
  const ticket = enqueueWaiter({ lockPath, nowFn, fsImpl });
188
211
  try {
189
212
  const outcome = await pollForTurn(opts, ticket, clock);
@@ -205,17 +228,51 @@ function waitClock({ waitMs, reportMs, nowFn }) {
205
228
  };
206
229
  }
207
230
 
208
- function announceWait({ lockPath, waitMs, fsImpl, log }) {
209
- log(
210
- `${LOCK_TAG} ⏳ another full suite is already running on this host (${holderLabel(lockPath, fsImpl)}) — waiting up to ${Math.round(waitMs / 1000)}s for it to finish before spawning.`,
211
- );
231
+ function reportProgress(opts, clock, phase, ticket, knownHolder) {
232
+ try {
233
+ opts.onLockProgress?.({
234
+ phase,
235
+ waitedSeconds: clock.waited(),
236
+ waitBudgetSeconds: Math.round(Math.max(0, opts.waitMs) / 1000),
237
+ ...(phase === 'admitted'
238
+ ? {}
239
+ : waitContext(opts, ticket, knownHolder, clock.blocking)),
240
+ });
241
+ } catch {}
212
242
  }
213
243
 
214
- function giveUp({ lockPath, fsImpl, nowFn, log, rerunCommand }, clock) {
244
+ /** Holder, queue position and what blocks admission, each when known. */
245
+ function waitContext(opts, ticket, known, blocking) {
246
+ const { lockPath, staleMs, fsImpl, nowFn } = opts;
247
+ const holder = known ?? waitHolder(opts, blocking);
248
+ const queueAhead = countAhead({ lockPath, ticket, staleMs, nowFn, fsImpl });
249
+ return {
250
+ ...(holder.ownerId === null && holder.pid === null ? {} : { holder }),
251
+ ...(queueAhead === null ? {} : { queueAhead }),
252
+ ...publicBlocking(blocking, queueAhead),
253
+ };
254
+ }
255
+
256
+ function waitHolder({ lockPath, fsImpl, nowFn }, blocking) {
257
+ return blocking?.holder ?? readLockHolder(lockPath, { fsImpl, nowFn });
258
+ }
259
+
260
+ function announceWait(opts) {
261
+ const line = admissionWaitLine(opts.workload, opts.blocking, opts.waitMs);
262
+ opts.log(line ?? exclusiveWaitLine(opts));
263
+ }
264
+
265
+ function exclusiveWaitLine({ lockPath, waitMs, fsImpl }) {
266
+ return `${LOCK_TAG} ⏳ another full suite is already running on this host (${holderLabel(lockPath, fsImpl)}) — waiting up to ${Math.round(waitMs / 1000)}s for it to finish before spawning.`;
267
+ }
268
+
269
+ function giveUp(opts, clock) {
270
+ const { lockPath, fsImpl, nowFn, log, rerunCommand } = opts;
215
271
  const holder = readLockHolder(lockPath, { fsImpl, nowFn });
216
272
  log(
217
273
  `${LOCK_TAG} ⌛ gave up waiting for the full-suite lock (waited ${clock.waited()}s, ${describeHolder(holder)}) — not spawning, so two full suites never overlap. Re-run once it finishes: ${rerunCommand}`,
218
274
  );
275
+ reportProgress(opts, clock, 'expired', null, holder);
219
276
  return {
220
277
  held: null,
221
278
  expired: true,
@@ -232,25 +289,35 @@ async function pollForTurn(opts, ticket, clock) {
232
289
  await opts.sleepFn(Math.max(0, opts.pollMs));
233
290
  refreshTicket(ticket, { nowFn, fsImpl });
234
291
  const attempt = isFirstInLine({ lockPath, ticket, staleMs, nowFn, fsImpl })
235
- ? opts.acquireOnceFn({ lockPath, timeoutMs: staleMs, fsImpl })
236
- : { acquired: false };
292
+ ? opts.attempt.tryOnce()
293
+ : { acquired: false, blocking: { reason: 'queue' } };
294
+ clock.blocking = attempt.blocking ?? null;
237
295
  if (attempt.acquired) {
238
- log(
239
- `${LOCK_TAG} ✅ acquired the full-suite lock (waited ${clock.waited()}s).`,
240
- );
296
+ log(acquiredLine(opts.workload, clock.waited()));
297
+ reportProgress(opts, clock, 'admitted', ticket);
241
298
  return { held: attempt, expired: false };
242
299
  }
243
300
  // A hard I/O error will not resolve by waiting; it is not an expiry.
244
301
  if (attempt.reason === 'error') return { held: null, expired: false };
245
- reportStillWaiting(opts, clock);
302
+ reportStillWaiting(opts, clock, ticket);
246
303
  }
247
304
  return null;
248
305
  }
249
306
 
250
- function reportStillWaiting({ lockPath, fsImpl, nowFn, log, reportMs }, clock) {
307
+ function acquiredLine(workload, waited) {
308
+ return (
309
+ admittedLine(workload, waited) ??
310
+ `${LOCK_TAG} ✅ acquired the full-suite lock (waited ${waited}s).`
311
+ );
312
+ }
313
+
314
+ function reportStillWaiting(opts, clock, ticket) {
315
+ const { lockPath, fsImpl, nowFn, log, reportMs } = opts;
251
316
  if (nowFn() < clock.nextReport) return;
317
+ const reason = blockingLabel(clock.blocking) ?? holderLabel(lockPath, fsImpl);
252
318
  log(
253
- `${LOCK_TAG} ⏳ still waiting for the full-suite lock (${holderLabel(lockPath, fsImpl)}, waited ${clock.waited()}s).`,
319
+ `${LOCK_TAG} ⏳ still waiting for the full-suite lock (${reason}, waited ${clock.waited()}s).`,
254
320
  );
321
+ reportProgress(opts, clock, 'still-waiting', ticket);
255
322
  clock.nextReport += reportMs;
256
323
  }