Skip to content

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 backendWorkersStartup to repliesCombined worker RSSCombined worker PSS
Porffor compiled111.50 ms4.25 MiB2.72 MiB
Node.js process194.33 ms62.65 MiB38.47 MiB
Porffor compiled417.67 ms16.88 MiB9.39 MiB
Node.js process4106.00 ms249.31 MiB101.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.

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 .knt file 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.

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 only task, isMain, and createPool. APIs such as Envelope, importTask, and checkCompiledWorker do 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:fs or node: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 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:

Terminal window
bun run build:compiled --module tasks.ts --out ./build/tasks-linux-x64.knt --tasks hello

Configure the host to load that artifact:

const pool = createPool({
worker: {
runtime: "compiled",
compiled: {
artifact: "./build/tasks-linux-x64.knt",
build: false,
},
},
})({ hello });

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.

When Knitting needs to build automatically, it looks for Porffor in this order:

  1. worker.compiled.compiler
  2. PORFFOR_MAIN or PORF
  3. porf on PATH

If it cannot find one, Knitting downloads a pinned compiler to $XDG_CACHE_HOME/knitting or, when that variable is not set, ~/.cache/knitting.

Compiled workers support fewer payload types than regular thread and process workers:

ValueBehavior
JSON primitives, arrays, and plain objectsCopied; limited to 1 MiB per call
ArrayBuffer, DataView, and typed arraysCopied
ProcessSharedBufferMapped by the worker instead of copied
Promise<supported>Resolved on the host before dispatch
Envelope, BufferReference, and BigInt typed arraysRejected

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.

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.

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:

OptionWhy it is unsupported
inliner, hostThere is no compiled equivalent of a host-side lane.
permissionNative artifacts do not use runtime permission flags.
worker.bootstrapThe worker does not import a host bootstrap module.
worker.timers, task timeoutThe compiled worker has no timer scheduler.
importTaskThe compiler needs the task body at build time.
payload, unsafe, source, workerExecArgvThese options belong to the regular frame transport.
worker.processCommandPrefix, worker.processSharedMemory, worker.resolveAfterFinishingAllThese 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.