@isentinel/machine-budget 0.0.0-stage → 0.2.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.
- package/LICENSE.md +21 -0
- package/README.md +105 -2
- package/bin/machine-budget-status.js +15 -0
- package/dist/admission-DcnnK4uq.d.mts +35 -0
- package/dist/index.d.mts +92 -0
- package/dist/index.mjs +675 -0
- package/dist/run-text-1kRifnCt.mjs +663 -0
- package/dist/status-cli.d.mts +53 -0
- package/dist/status-cli.mjs +51 -0
- package/package.json +39 -3
package/LICENSE.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Christopher Buss
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,106 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @isentinel/machine-budget
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Leases memory and threads to Node dev tools from one budget shared by the whole
|
|
4
|
+
machine. Two lint runs in two worktrees, a mutation test and a type check each
|
|
5
|
+
ask the budget before they start workers, so together they do not run the
|
|
6
|
+
machine out of memory.
|
|
7
|
+
|
|
8
|
+
The budget is a SQLite ledger (`node:sqlite`) in the system temp directory.
|
|
9
|
+
Every process of one user on one machine opens the same ledger. A process that
|
|
10
|
+
dies loses its leases at the next lease attempt of any other process.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm install --save-dev @isentinel/machine-budget
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Requires Node 24.12 or later, or Bun 1.4 or later.
|
|
19
|
+
|
|
20
|
+
## Use
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { openMachineBudget } from "@isentinel/machine-budget";
|
|
24
|
+
|
|
25
|
+
const budget = openMachineBudget({ log: console.error, workspaceRoot });
|
|
26
|
+
const lease = await budget.leaseAsync({
|
|
27
|
+
cost: { pass: "type-aware", project: "app" },
|
|
28
|
+
maxWorkers: 6,
|
|
29
|
+
memoryPerWorker: 2 * 2 ** 30,
|
|
30
|
+
minWorkers: 1,
|
|
31
|
+
});
|
|
32
|
+
// Start the child with lease.workers workers.
|
|
33
|
+
lease.release({ peakMemory });
|
|
34
|
+
budget.close();
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`leaseAsync` waits until the minimum fits, then grants the most workers that
|
|
38
|
+
fit. A request with a `cost` uses the learned memory of one worker once three
|
|
39
|
+
peaks are known, and `memoryPerWorker` before that. Costs are kept per git
|
|
40
|
+
clone: all worktrees of one clone share them. A waiting request prints a line
|
|
41
|
+
through `log` that names the reason and each other run that holds leases: its
|
|
42
|
+
pid, its `workspaceRoot`, and its leased memory and threads. Behind an older
|
|
43
|
+
request, the line names the run of that request and its size instead. It prints
|
|
44
|
+
again when the reason or the named runs change. `isShared` is true when leases
|
|
45
|
+
come from the shared ledger, and false when the budget is off.
|
|
46
|
+
|
|
47
|
+
A run that resizes while it runs holds one lease for each worker. `tryLease`
|
|
48
|
+
grants the most workers that fit now, or returns `undefined`, and never waits.
|
|
49
|
+
`runCapWorkers` tells how many workers of a request the run cap lets the run
|
|
50
|
+
hold now, its own leases included; the run frees leases above it. A request with
|
|
51
|
+
`isMainLaneOnly` never takes the small-job lane, for leases held long.
|
|
52
|
+
|
|
53
|
+
## Measure a process tree
|
|
54
|
+
|
|
55
|
+
A child that runs its workers as separate processes reports two peaks:
|
|
56
|
+
`peakMemory` for the whole tree and `peakPerWorker` for its biggest worker. A
|
|
57
|
+
release with `peakPerWorker` learns that value as the memory of one worker, in
|
|
58
|
+
place of `peakMemory` divided by the workers.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import { watchTree } from "@isentinel/machine-budget";
|
|
62
|
+
|
|
63
|
+
import assert from "node:assert";
|
|
64
|
+
|
|
65
|
+
const child = spawn(process.execPath, ["pool.js", String(lease.workers)], {
|
|
66
|
+
windowsHide: true,
|
|
67
|
+
});
|
|
68
|
+
assert(child.pid !== undefined);
|
|
69
|
+
const watch = watchTree(child.pid);
|
|
70
|
+
await once(child, "exit");
|
|
71
|
+
const { peakMemory, peakPerWorker } = watch.stop();
|
|
72
|
+
lease.release({ peakMemory: peakMemory ?? 0, peakPerWorker });
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Call `watchTree` right after the spawn. It samples the tree ten times a second,
|
|
76
|
+
so a process that starts and exits between two samples is missed.
|
|
77
|
+
|
|
78
|
+
- Windows: the child joins a Job Object. `peakMemory` is the peak commit of the
|
|
79
|
+
job, and `peakPerWorker` is the highest peak commit of one descendant.
|
|
80
|
+
- Linux: `peakPerWorker` is the highest peak resident set (`VmHWM`) of one
|
|
81
|
+
descendant, and `peakMemory` is the highest sum of resident sets over the
|
|
82
|
+
samples.
|
|
83
|
+
- Elsewhere both peaks are `undefined`. `watchTree` never throws.
|
|
84
|
+
|
|
85
|
+
## Environment
|
|
86
|
+
|
|
87
|
+
- `MACHINE_BUDGET=off` grants every request its maximum at once. `CI` set to any
|
|
88
|
+
value other than `false` does the same.
|
|
89
|
+
- `MACHINE_BUDGET_DIR` moves the ledger. The default is `machine-budget-<user>`
|
|
90
|
+
in the system temp directory.
|
|
91
|
+
|
|
92
|
+
## See the ledger
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
npx machine-budget-status
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`machine-budget-status` prints each run with its pid, its `workspaceRoot` and
|
|
99
|
+
the age of its heartbeat; each lease with its run, lane, memory and threads; and
|
|
100
|
+
each waiting request with its run, size and wait time. It opens the ledger
|
|
101
|
+
read-only: it does not take back dead runs or make the ledger, and it honours
|
|
102
|
+
`MACHINE_BUDGET_DIR`. In this repo, `pnpm machine-budget:status` runs it.
|
|
103
|
+
|
|
104
|
+
## License
|
|
105
|
+
|
|
106
|
+
MIT
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { dirname, resolve } from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
|
|
6
|
+
const sourceEntry = resolve(dirname(fileURLToPath(import.meta.url)), "../src/status-cli.ts");
|
|
7
|
+
|
|
8
|
+
let main;
|
|
9
|
+
if (existsSync(sourceEntry)) {
|
|
10
|
+
({ main } = await import("../src/status-cli.ts"));
|
|
11
|
+
} else {
|
|
12
|
+
({ main } = await import("../dist/status-cli.mjs"));
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
main();
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** A lease that a session holds. */
|
|
2
|
+
interface HeldLease {
|
|
3
|
+
/** The pool of the lease. */
|
|
4
|
+
lane: Lane;
|
|
5
|
+
/** The leased memory, in bytes. */
|
|
6
|
+
memory: number;
|
|
7
|
+
/** The session that holds the lease. */
|
|
8
|
+
session: string;
|
|
9
|
+
/** The leased threads. */
|
|
10
|
+
threads: number;
|
|
11
|
+
}
|
|
12
|
+
/** A request that waits for a lease. */
|
|
13
|
+
interface Waiter {
|
|
14
|
+
/** The id of the request. */
|
|
15
|
+
id: string;
|
|
16
|
+
/** Whether the request is too big for the small-job lane. */
|
|
17
|
+
isBig: boolean;
|
|
18
|
+
/** The session that made the request. */
|
|
19
|
+
session: string;
|
|
20
|
+
/** When the request started to wait, in epoch milliseconds. */
|
|
21
|
+
since: number;
|
|
22
|
+
}
|
|
23
|
+
/** The worker range and the memory of one worker. */
|
|
24
|
+
interface WorkerRequest {
|
|
25
|
+
/** Keeps the request out of the small-job lane, for leases held long. */
|
|
26
|
+
isMainLaneOnly?: boolean;
|
|
27
|
+
/** The most workers the client can use. */
|
|
28
|
+
maxWorkers: number;
|
|
29
|
+
/** The memory of one worker, in bytes. */
|
|
30
|
+
memoryPerWorker: number;
|
|
31
|
+
/** The fewest workers the client can run with. */
|
|
32
|
+
minWorkers: number;
|
|
33
|
+
}
|
|
34
|
+
type Lane = "main" | "small";
|
|
35
|
+
export { Waiter as n, WorkerRequest as r, HeldLease as t };
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import { r as WorkerRequest } from "./admission-DcnnK4uq.mjs";
|
|
2
|
+
/** What a cost is learned for, inside one clone. */
|
|
3
|
+
interface CostScope {
|
|
4
|
+
/** The pass of the tool, such as `type-aware`. */
|
|
5
|
+
pass: string;
|
|
6
|
+
/** The project the worker runs for. */
|
|
7
|
+
project: string;
|
|
8
|
+
}
|
|
9
|
+
/** What one child process asks for. */
|
|
10
|
+
interface LeaseRequest extends WorkerRequest {
|
|
11
|
+
/** What to learn the cost for; without it, `memoryPerWorker` is used. */
|
|
12
|
+
cost?: CostScope;
|
|
13
|
+
}
|
|
14
|
+
/** What a client reports when its child exits. */
|
|
15
|
+
interface LeaseReport {
|
|
16
|
+
/** The peak memory of the child process, in bytes. */
|
|
17
|
+
peakMemory: number;
|
|
18
|
+
/**
|
|
19
|
+
* The highest peak of one worker process, in bytes; learned as is when
|
|
20
|
+
* given.
|
|
21
|
+
*/
|
|
22
|
+
peakPerWorker?: number;
|
|
23
|
+
}
|
|
24
|
+
/** Memory and threads that one child process holds. */
|
|
25
|
+
interface Lease {
|
|
26
|
+
/** The memory of one worker that the lease counts, in bytes. */
|
|
27
|
+
memoryPerWorker: number;
|
|
28
|
+
/** Gives the memory and threads back, and records the peak if reported. */
|
|
29
|
+
release: (report?: LeaseReport) => void;
|
|
30
|
+
/** The workers that the child may run. */
|
|
31
|
+
workers: number;
|
|
32
|
+
}
|
|
33
|
+
/** The machine budget, as one run sees it. */
|
|
34
|
+
interface MachineBudget {
|
|
35
|
+
/** Leaves the budget and gives back every lease of the run. */
|
|
36
|
+
close: () => void;
|
|
37
|
+
/** True when leases come from the ledger that other runs share. */
|
|
38
|
+
readonly isShared: boolean;
|
|
39
|
+
/** Waits until the request fits, then leases the most workers that fit. */
|
|
40
|
+
leaseAsync: (request: LeaseRequest) => Promise<Lease>;
|
|
41
|
+
/** The most workers of the request that the run cap lets this run hold. */
|
|
42
|
+
runCapWorkers: (request: LeaseRequest) => number;
|
|
43
|
+
/** Leases the most workers that fit now, or nothing, and never waits. */
|
|
44
|
+
tryLease: (request: LeaseRequest) => Lease | undefined;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The peaks of a process tree in bytes, undefined where the platform cannot
|
|
48
|
+
* read them.
|
|
49
|
+
*/
|
|
50
|
+
interface TreePeaks {
|
|
51
|
+
/** The peak memory of the whole tree. */
|
|
52
|
+
peakMemory: number | undefined;
|
|
53
|
+
/**
|
|
54
|
+
* The highest peak of one descendant, which a lease reports as
|
|
55
|
+
* `peakPerWorker`.
|
|
56
|
+
*/
|
|
57
|
+
peakPerWorker: number | undefined;
|
|
58
|
+
}
|
|
59
|
+
/** A watch on a running process and every process it starts. */
|
|
60
|
+
interface TreeWatch {
|
|
61
|
+
/** Stops the watch and returns the peaks since it began. */
|
|
62
|
+
stop: () => TreePeaks;
|
|
63
|
+
}
|
|
64
|
+
/** How a run joins the machine budget. */
|
|
65
|
+
export interface MachineBudgetOptions {
|
|
66
|
+
/** Prints the one line of a waiting request, such as `console.error`. */
|
|
67
|
+
log: (line: string) => void;
|
|
68
|
+
/** The root of the clone that runs; its git common directory keys costs. */
|
|
69
|
+
workspaceRoot: string;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Joins the budget that every dev tool on this machine shares. Close it when
|
|
73
|
+
* the run ends; a run that dies is taken back by the next run that leases.
|
|
74
|
+
* `MACHINE_BUDGET=off` or CI turns it off, and `MACHINE_BUDGET_DIR` moves the
|
|
75
|
+
* ledger.
|
|
76
|
+
*
|
|
77
|
+
* @param options - The logger and the workspace root.
|
|
78
|
+
* @returns The budget of this run.
|
|
79
|
+
*/
|
|
80
|
+
export declare function openMachineBudget(options: MachineBudgetOptions): MachineBudget;
|
|
81
|
+
/**
|
|
82
|
+
* Watches a running process and every process it starts from now on, to
|
|
83
|
+
* report the peaks that a lease release takes. Call it right after the spawn;
|
|
84
|
+
* a descendant that starts and ends between two samples is missed. On Windows
|
|
85
|
+
* the root joins a Job Object; on Linux the peaks are resident sets read from
|
|
86
|
+
* `/proc`; elsewhere both peaks are undefined. It never throws.
|
|
87
|
+
*
|
|
88
|
+
* @param pid - The pid of the process at the top of the tree.
|
|
89
|
+
* @returns The watch; stop it once the process exits.
|
|
90
|
+
*/
|
|
91
|
+
export declare function watchTree(pid: number): TreeWatch;
|
|
92
|
+
export type { CostScope, Lease, LeaseReport, LeaseRequest, MachineBudget, TreePeaks, TreeWatch };
|