API reference / @jsprismarine/chunkgen / GenerationPool
Class: GenerationPool
Defined in: GenerationPool.ts:587
Runs status bodies in worker threads.
The main thread keeps the holders, the scheduler, the feature patch merge and the translation to Bedrock runtime ids. A worker only ever sees one chunk's worth of work and hands back flat typed arrays.
Constructors
Constructor
new GenerationPool(
options,runner?):GenerationPool
Defined in: GenerationPool.ts:660
Parameters
options
The pipeline module, the worker entry, the worker count and the setup.
runner?
TaskRunnerFactory = piscinaRunner
How to build the task runner. Defaults to piscina; a test passes a double.
Returns
GenerationPool
Properties
options
readonlyoptions:GenerationPoolOptions
Defined in: GenerationPool.ts:661
The pipeline module, the worker entry, the worker count and the setup.
Accessors
inFlight
Get Signature
get inFlight():
number
Defined in: GenerationPool.ts:712
How many tasks the workers are holding right now.
Returns
number
queued
Get Signature
get queued():
number
Defined in: GenerationPool.ts:717
How many tasks are waiting for a worker, across every band.
Returns
number
workers
Get Signature
get workers():
number
Defined in: GenerationPool.ts:707
How many workers are up. Zero once the pool has been shut down.
Returns
number
Methods
cancel()
cancel(
wanted):number
Defined in: GenerationPool.ts:765
Drops every waiting task a predicate picks out, and reports how many went.
Only the backlog: a task a worker already has cannot be taken back without terminating the worker, which costs more than letting the chunk finish. That is the right trade for what this is for - a player turning around leaves an idle rim nobody will ever look at, and the few already running are the cheapest part of it.
Parameters
wanted
(task) => boolean
Answers true for a task that should still be built.
Returns
number
How many tasks were dropped.
destroy()
destroy():
Promise<void>
Defined in: GenerationPool.ts:825
Stops every worker, interrupting whatever they are doing.
Worker threads do not receive signals, so terminating them is the only way to stop one mid-chunk. Measured at 2 to 24 ms for a worker in a tight loop.
Everything still in the backlog is refused first, so a shutdown does not leave a caller waiting on a turn that is never going to come.
Returns
Promise<void>
promote()
promote(
wanted,to):number
Defined in: GenerationPool.ts:797
Moves waiting tasks up into a band, and reports how many moved.
What a chunk that has become more urgent needs. A rim chunk asked for as idle is the same chunk a player is standing on a moment later, and without this it would keep the turn it was given when nobody wanted it. A task already in the band or above it is left where it is, so this only ever moves work forward.
Order inside the destination band is arrival order, and a promoted task arrives now: it goes behind everything already waiting there, not in front of it.
Parameters
wanted
(task) => boolean
Answers true for a task that should move.
to
"immediate" | "soon" | "idle"
The band to move it into.
Returns
number
How many tasks moved.
resetStats()
resetStats():
void
Defined in: GenerationPool.ts:679
Forgets the recorded task stats.
Returns
void
run()
run(
task,priority?):Promise<GenerationResult>
Defined in: GenerationPool.ts:741
Runs one status body in whichever worker is free.
A task above the in-flight limit waits here rather than downstream, so a request that arrives while the queue is long is still served in GenerationPriority order instead of behind everything that was asked for first.
Parameters
task
The status, the position and whatever else the body reads.
priority?
"immediate" | "soon" | "idle" = 'immediate'
Which band the task waits in. Defaults to immediate, so a caller that has not thought about it gets the behavior it would have had with no queue at all.
Returns
Promise<GenerationResult>
What the body produced, with its buffers now owned by this thread.
Throws
GenerationPoolClosedError when the pool has been shut down, whether that was before the task was asked for or while it was waiting.
Throws
GenerationCanceledError when GenerationPool.cancel dropped it.
Throws
Whatever the body threw, so a worker that fails rejects the request rather than leaving it outstanding forever.
setBackgroundLimit()
setBackgroundLimit(
limit):void
Defined in: GenerationPool.ts:692
Limits how many soon and idle tasks may be with workers at once. immediate tasks never count against it and are never held back by it, so a chunk a player stands on is not slowed.
Raising the limit starts waiting tasks at once. Lowering it does not interrupt a task a worker has: the running count falls as they finish.
Parameters
limit
number | undefined
The most background tasks at once, or undefined for no limit.
Returns
void
statsSnapshot()
statsSnapshot():
GenerationStatsSnapshot
Defined in: GenerationPool.ts:674
What the pool has recorded about the tasks it ran, by status and priority band.
Returns
A copy, so a caller can take two and subtract.
unavailable()
staticunavailable(options):string|undefined
Defined in: GenerationPool.ts:622
Why this process cannot run workers, or undefined when it can.
A worker thread is a second module loader rather than a copy of this one. The Node single executable packages its worker and pipelines as assets; other hosts need those modules available through Node's resolution. Asking before building lets a caller log one line and do the work on its own thread instead of starting workers that cannot import modules.
This does not promise the pipeline imports cleanly once a worker has it. That depends on the loader the host was started with, which only the import itself can settle, so a caller still needs a fallback for the first task.
Parameters
options
The options GenerationPool would be built with.
Returns
string | undefined
A sentence naming what is missing, or undefined when nothing is.