NodeJsHostOptions Class

Limiting the number of calls bounds the memory and the work queued in the Node.js process. With NodeJsHostPool, calls wait in the pool and run on the first process that becomes available, which balances calls of different durations; 1 is a good value for CPU-bound code.

With NodeJsHostOptions.WorkerThreads, the limit applies to the calls of all the worker threads of the process, and each call that can run is sent to the worker thread with the fewest calls in progress. Use the number of worker threads for CPU-bound code, so a call runs on a worker thread that becomes available instead of waiting for a long call.

A canceled call no longer counts, even if its JavaScript code is still running. A call made using NodeJsHostPool.RunAsync counts as one call of the pool, and each call it makes on the host counts as one call of the host.

Canceling a call does not stop its JavaScript code, and synchronous code blocks all the other calls of the process. Killing the process is the only way to stop it. The calls in progress then fail with a NodeJsException whose NodeJsException.ExitCode is null, and NodeJsHostPool replaces the process the next time a host is selected.

The process is killed only when the code blocking its event loop belongs to a canceled call, including code run by the promises, timeouts, and I/O operations it started. Code run by long-lived objects (intervals, sockets, servers, event listeners on objects the call did not create...) and the code that loads a module imported by NodeJsHost.InvokeAsync or require belong to no call, as they can run code for several calls. Calls that are not canceled are never stopped, even when they keep the event loop busy for longer. While canceled calls are running, the process is checked at least every second, so a canceled call that blocks the event loop after awaiting is also stopped. Choose a value larger than the longest synchronous step of a canceled call that must not be stopped.

To know which call runs, the process tracks the asynchronous context of each call using node:async_hooks, which slows down code that awaits many promises, and a watchdog thread answers the host while the event loop is blocked.

With NodeJsHostOptions.WorkerThreads, only the worker thread blocked by a canceled call is terminated and restarted: the calls in progress on this worker thread fail, the other worker threads are not affected, and the process keeps running. The main thread of the process, which does not run calls, answers the host.

Each call runs on one worker thread: the one with the fewest calls in progress, or, when the call uses a JSReference, the one that keeps the referenced value. Worker threads do not share state: each one has its own globalThis, loads its own modules, and keeps its own referenced values, so consecutive calls may run on different worker threads and not see the same values. A call cannot use references kept by different worker threads.

A worker thread that exits (e.g. calling process.exit()) is restarted: the calls in progress on it fail with a NodeJsException whose NodeJsException.ExitCode is null, and its referenced values are lost. Some APIs behave differently in a worker thread: process.exit() only stops the worker thread, process.chdir() is not supported, process.env is a copy, and native addons must support worker threads.