placement-pool

Classes

PlacementPool

Defined in: tar/src/placement-pool.ts:81

A pool of worker threads that each unpack tarballs into place. See placement-worker.ts for why, and for why store links are not here.

Workers are started by warm, which reify calls as soon as it knows how many packages it will place, so they boot while the first packages are being fetched rather than on the critical path of the first placement. A pool that was never warmed starts its workers on its own once it has seen minJobs placements, so an install that places as it resolves still gets them. Each worker reports when it is ready, and jobs queue until one is. Below minJobs packages, warm starts nothing and everything stays inline.

An idle worker is unrefd so it does not keep the process alive, and refd again while it holds a job, so the pool needs no explicit close to let the process exit -- though reify calls it anyway, to free the threads as soon as placement is done.

With a size below 2 (a kill switch, one core, or no spare core) there are no workers at all: placement runs inline, exactly as before.

Constructors

new PlacementPool()

new PlacementPool(
   size, 
   minJobs, 
   heldMax): PlacementPool

Defined in: tar/src/placement-pool.ts:101

Parameters

Returns

PlacementPool

Accessors

heldBytes

Get Signature

get heldBytes(): number

Defined in: tar/src/placement-pool.ts:139

Compressed bytes downloaded and waiting for, or in, an unpack.

Returns

number

inline

Get Signature

get inline(): boolean

Defined in: tar/src/placement-pool.ts:112

True when placement runs inline, with no worker threads.

Returns

boolean

readyCount

Get Signature

get readyCount(): number

Defined in: tar/src/placement-pool.ts:134

Number of workers that have booted and can take jobs (for tests).

Returns

number

threaded

Get Signature

get threaded(): boolean

Defined in: tar/src/placement-pool.ts:117

True once the workers were started and placement goes to them.

Returns

boolean

workerCount

Get Signature

get workerCount(): number

Defined in: tar/src/placement-pool.ts:129

Number of worker threads spawned so far (for tests).

Returns

number

Methods

close()

close(): Promise<void>

Defined in: tar/src/placement-pool.ts:438

Terminate every worker. Safe to call more than once. Any placement still assigned or queued is rejected rather than left hanging, since terminating a worker stops it before it can reply, and a warm() still waiting on the boot is released.

Returns

Promise<void>

unpack()

unpack(
   tarData, 
   target, 
format?): Promise<void>

Defined in: tar/src/placement-pool.ts:210

Unpack tarData into target: on a worker once the pool is threaded, inline otherwise (inflating on libuv's threadpool and writing on the main thread, as before this pool existed). Resolves when the files are in place.

The bytes are copied before they go to a worker: the caller may still hold them (the registry client caches its response bodies), and a transfer would detach them for everyone. For a tarball that is already on disk, unpackCacheEntry avoids the copy.

Parameters

Returns

Promise<void>

unpackCacheEntry()

unpackCacheEntry(
   file, 
   target, 
format?): Promise<void>

Defined in: tar/src/placement-pool.ts:248

Unpack the tarball in the vlt cache entry file into target. A worker reads the file itself, so the main thread neither reads nor copies the body, and nothing is held against the byte cap. Inline when the pool is not threaded, like unpack.

Parameters

Returns

Promise<void>

warm()

warm(jobs): Promise<void>

Defined in: tar/src/placement-pool.ts:151

Start the workers for an install that will place jobs packages, so they boot now rather than when the first placement arrives. Starts nothing, leaving placement inline, when the pool is inline or closed, when it was already warmed, or when jobs is below the minimum. Resolves once every worker it started is ready or gone; it never rejects, so a caller may fire and forget it.

Parameters

Returns

Promise<void>

Variables

DEFAULT_HELD_BYTES

const DEFAULT_HELD_BYTES: number;

Defined in: tar/src/placement-pool.ts:51

How many bytes of downloaded tarballs may wait for an unpack worker. A tarball that would push past the cap waits for room before it is handed over; one larger than the whole cap goes as soon as nothing else is held. The cap applies after the download, so the downloads still in flight are bounded by the caller's concurrency, not by this.

DEFAULT_PLACEMENT_MIN_JOBS

const DEFAULT_PLACEMENT_MIN_JOBS: 100 = 100;

Defined in: tar/src/placement-pool.ts:42

Below this many packages an install places inline. On a small machine (two cores, two threads each) three workers take 60 to 90ms to boot, which a 60-package install cannot earn back: it measured 16% slower with a pool than without. A 400-package install does earn it back.

Functions

placementThreads()

function placementThreads(): number

Defined in: tar/src/placement-pool.ts:26

How many placement worker threads to run.

VLT_PLACEMENT_THREADS overrides it: 1 (and, as a safety net, anything that is not an integer >= 1) places inline on the main thread, the behaviour from before this pool existed and a field kill switch.

The default is one worker per core, less one for the main thread, capped at 8: past the inflate, placement is write/mkdir syscalls, whose metadata locks stop rewarding more threads well before the core count on the machines this was measured on. One core (or zero spare) resolves to 1, i.e. inline.

Returns

number