Compiled workers
Compiled workers use Porffor to compile
JavaScript tasks into native executables. Knitting runs them as child processes
while keeping the same task definitions and pool.call.*() API.
This backend suits small, synchronous, self-contained CPU tasks. For tasks that need I/O, timers, or Node.js built-ins, use regular thread workers or process workers.
Startup and worker memory compared with Node.js processes
Section titled “Startup and worker memory compared with Node.js processes”In a small numeric-task benchmark, Porffor workers used about 93% less resident memory (RSS) than Knitting’s Node.js process workers. Both sides used Knitting; the memory measurements below include only the worker processes, excluding the host.
| Knitting worker backend | Workers | Startup to replies | Combined worker RSS | Combined worker PSS |
|---|---|---|---|---|
| Porffor compiled | 1 | 11.50 ms | 4.25 MiB | 2.72 MiB |
| Node.js process | 1 | 94.33 ms | 62.65 MiB | 38.47 MiB |
| Porffor compiled | 4 | 17.67 ms | 16.88 MiB | 9.39 MiB |
| Node.js process | 4 | 106.00 ms | 249.31 MiB | 101.45 MiB |
Startup measures createPool() through a successful batch of one call per
configured worker. It excludes host loading, compilation, and shutdown.
RSS counts each process’s resident pages, so summing it can count shared pages more than once. PSS divides shared pages among the processes using them and better estimates physical RAM attributable to the workers.
These near-idle results use Knitting 0.1.77 and Porffor alpha 18. Larger tasks and payloads can use more memory.
Benchmark setup and measurements
These are medians of 10 measured runs per configuration, after one discarded
warmup run, on October 20, 2026. Each run started a fresh Node.js host and used
the built JavaScript entry point, with Knitting 0.1.77, Node.js 24.17.0, and
Porffor alpha 18 (deda494) on Linux x64 with an AMD Ryzen 7 4700U.
Node.js workers used
worker: { runtime: "process", processRuntime: "node" } and
permission: "unsafe"; compiled workers used a prebuilt artifact with
compiled.build: false. Alpha 18 was selected explicitly; these results do not
describe Knitting’s default pinned compiler.
The task returned its numeric argument plus one. The startup batch does not
establish that every individual worker handled a call. Memory was sampled from
Linux /proc 300 ms after a successful batch of one call per configured worker,
with default allocation sizes and no forced garbage collection. These are
near-idle measurements rather than workload peak memory.
Download the measurements and environment details.
Start a compiled worker
Section titled “Start a compiled worker”If your task module is tasks.ts, Knitting will look beside it for two
files: the compiled program, tasks.knt, and its manifest,
tasks.knt.json.
Save this example as tasks.ts. The worker configuration selects Porffor and
reuses the compiled file whenever it is still valid:
import { createPool, isMain } from "knitting";
export const hello = (name: string) => "Hello " + name;
if (isMain) { using pool = createPool({ worker: { runtime: "compiled", processRuntime: "porffor" }, })({ hello });
console.log(await pool.call.hello("World!")); // Hello World!}Each setting has a separate job:
runtime: "compiled"reuses a compatible.kntfile and rebuilds it if it is missing, stale, or no longer matches the current setup.processRuntime: "porffor"selects Porffor. Used by itself, it rebuilds once for each pool.
If the pool has several workers, Knitting still compiles the module only once; all of the native workers start from the same artifact.
Keep the task module self-contained
Section titled “Keep the task module self-contained”Porffor bundles the task module and everything it imports. That works well for small, self-contained computations, but it means the task module has to stay simple.
There are two rules worth knowing:
- From
knitting, import onlytask,isMain, andcreatePool. APIs such asEnvelope,importTask, andcheckCompiledWorkerdo not have compiled-worker equivalents and will make the build fail. Keep host-only code in a separate module when you need it. - Do not import Node.js built-ins such as
node:fsornode:crypto. Porffor does not provide them, and some unsupported imports can hang the compiler instead of producing a useful error. Plain local modules are fine.
Build artifacts ahead of time
Section titled “Build artifacts ahead of time”Build the artifact in CI or during your release step to keep compilation out
of production startup. From a Knitting checkout, build the hello task above:
bun run build:compiled --module tasks.ts --out ./build/tasks-linux-x64.knt --tasks helloConfigure the host to load that artifact:
const pool = createPool({ worker: { runtime: "compiled", compiled: { artifact: "./build/tasks-linux-x64.knt", build: false, }, },})({ hello });Rebuilds and compatibility
Section titled “Rebuilds and compatibility”The worker.compiled.build option controls when Knitting is allowed to build:
true— build only when the artifact cannot be reused;false— never build; fail if the artifact is unavailable;"always"— rebuild every time.
Use worker.compiled.manifest when the sidecar manifest is somewhere else.
Before starting a worker, Knitting checks that the manifest still matches the
protocol version, platform, architecture, source module, source timestamp, and
requested task names.
If you want to check this yourself, checkCompiledWorker(task, options) reports
the compatibility state without building the artifact or running the task.
Compiler selection
Section titled “Compiler selection”When Knitting needs to build automatically, it looks for Porffor in this order:
worker.compiled.compilerPORFFOR_MAINorPORFporfonPATH
If it cannot find one, Knitting downloads a pinned compiler to
$XDG_CACHE_HOME/knitting or, when that variable is not set,
~/.cache/knitting.
Capabilities and limits
Section titled “Capabilities and limits”Supported values
Section titled “Supported values”Compiled workers support fewer payload types than regular thread and process workers:
| Value | Behavior |
|---|---|
| JSON primitives, arrays, and plain objects | Copied; limited to 1 MiB per call |
ArrayBuffer, DataView, and typed arrays | Copied |
ProcessSharedBuffer | Mapped by the worker instead of copied |
Promise<supported> | Resolved on the host before dispatch |
Envelope, BufferReference, and BigInt typed arrays | Rejected |
There are two other limits to keep in mind: task functions must be synchronous, so returning a promise is not supported, and strings may contain BMP characters but not supplementary Unicode code points yet.
For large binary data, use ProcessSharedBuffer. It is the one payload type
that a compiled worker maps directly instead of copying through the call frame.
See Shared memory to get started with it.
Cooperative cancellation
Section titled “Cooperative cancellation”You can also use cooperative cancellation on POSIX systems. Knitting publishes the abort state in named shared memory, and the compiled worker reads it directly instead of asking the host on every check.
import { task } from "knitting";
export const search = task({ abortSignal: true, f: (limit: number, signal) => { for (let i = 0; i < limit; i++) { if (signal.hasAborted()) return i; } return limit; },});signal.now() returns a monotonic millisecond clock for measuring elapsed time
inside the task. Cancellation is cooperative: if the task never checks the
signal, it continues until it finishes. Windows support is not available yet.
Unsupported options
Section titled “Unsupported options”Porffor is intentionally a smaller backend for now. The options below fail during pool creation or invocation instead of quietly switching to another worker type:
| Option | Why it is unsupported |
|---|---|
inliner, host | There is no compiled equivalent of a host-side lane. |
permission | Native artifacts do not use runtime permission flags. |
worker.bootstrap | The worker does not import a host bootstrap module. |
worker.timers, task timeout | The compiled worker has no timer scheduler. |
importTask | The compiler needs the task body at build time. |
payload, unsafe, source, workerExecArgv | These options belong to the regular frame transport. |
worker.processCommandPrefix, worker.processSharedMemory, worker.resolveAfterFinishingAll | These are process-worker options with no compiled equivalent. |
worker.hardTimeoutMs is the exception: it works because the host enforces it
from outside the compiled worker.
If you need one of these features, use a regular process worker instead. See Process workers.