perf(bench): split instantiation from decode/encode kernel measurement

The previous codec benches conflated three costs into one number:
constructor + buffer fill + decode/encode + destructor. CodSpeed runs
each bench body exactly once under Cachegrind, so the per-iteration
construct/destroy cycle was sitting inside the measurement window —
and the variance analysis on a5b8ee6..fa2db51 showed exactly that
mixing was the source of the 18–110% run-to-run spread on
openjpeg encode CT1.RAW, openjpeg decode CT1.j2k, openjphjs encode
CT1.RAW, and libjpeg decode jpeg400jfif (the only four noisy benches
in the suite).

Refactor: hoist new Decoder()/Encoder() + getEncodedBuffer().set() /
getDecodedBuffer().set() / setNearLossless() to module scope, one
instance per fixture (wasm decoders advance internal state on
decode() and can't be reused across multiple bench bodies). Each
bench body is now a single decoder.decode() or encoder.encode() call.

Two new "instantiate+destroy" benches per codec measure the lifecycle
cost in isolation — that's where the noise was hiding and now it
shows up as its own number rather than smearing into the kernel
measurement.

Net effect: the 4 noisy benches should drop to <1% spread (matching
the dispatcher benches which already cache codec instances), and the
lifecycle cost gets its own signal line that catches regressions in
wasm setup paths.

Affected packages: charls, libjpeg-turbo-8bit, openjpeg, openjphjs.
big-endian/little-endian have no decoder class and dicom-codec's
dispatch.bench.js already caches codec instances via runProcess →
initialize → codecConfig.codec, so neither needs the same change.

Author: sedghi

packages/charls/bench/decode.bench.js

@@ -1,3 +1,11 @@
+// Decoder/encoder construction is hoisted to module scope so the bench
+// body only measures the decode/encode kernel itself. Each fixture gets
+// its own pre-constructed instance because the underlying wasm
+// JpegLSDecoder advances internal state on decode() and can't be reused
+// across multiple bench bodies. A separate "instantiate+destroy" bench
+// measures the lifecycle cost that the old monolithic bench was
+// conflating with kernel time.
+
 import { bench, describe } from "vitest"
 import { existsSync, readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
@@ -18,45 +26,59 @@ const ctNearLossless = !skip
   : null
 
 let codec
+let decCT1
+let decCT2
+let decNL
+let encCT2
 if (!skip) {
   const factory = (await import(distPath)).default ?? (await import(distPath))
   codec = await factory()
+
+  decCT1 = new codec.JpegLSDecoder()
+  decCT1.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
+
+  decCT2 = new codec.JpegLSDecoder()
+  decCT2.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
+
+  decNL = new codec.JpegLSDecoder()
+  decNL.getEncodedBuffer(ctNearLossless.length).set(ctNearLossless)
+
+  encCT2 = new codec.JpegLSEncoder()
+  encCT2
+    .getDecodedBuffer({
+      width: 512,
+      height: 512,
+      bitsPerSample: 16,
+      componentCount: 1,
+    })
+    .set(ct2Raw)
+  encCT2.setNearLossless(0)
 }
 
 describe.skipIf(skip)("charls JPEG-LS (wasm)", () => {
-  bench("decode CT1.JLS (.80 lossless, 512x512x16bit)", () => {
-    const decoder = new codec.JpegLSDecoder()
-    decoder.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("instantiate+destroy JpegLSDecoder", () => {
+    const d = new codec.JpegLSDecoder()
+    d.delete()
+  })
+
+  bench("instantiate+destroy JpegLSEncoder", () => {
+    const e = new codec.JpegLSEncoder()
+    e.delete()
+  })
+
+  bench("decode CT1.JLS (.80 lossless, 512x512x16bit) — kernel", () => {
+    decCT1.decode()
   })
 
-  bench("decode CT2.JLS (.80 lossless, 512x512x16bit)", () => {
-    const decoder = new codec.JpegLSDecoder()
-    decoder.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("decode CT2.JLS (.80 lossless, 512x512x16bit) — kernel", () => {
+    decCT2.decode()
   })
 
-  bench("decode CT-512x512-near-lossless.JLS (.81 near-lossless)", () => {
-    const decoder = new codec.JpegLSDecoder()
-    decoder.getEncodedBuffer(ctNearLossless.length).set(ctNearLossless)
-    decoder.decode()
-    decoder.delete()
+  bench("decode CT-512x512-near-lossless.JLS (.81 near-lossless) — kernel", () => {
+    decNL.decode()
   })
 
-  bench("encode CT2.RAW (lossless near=0)", () => {
-    const encoder = new codec.JpegLSEncoder()
-    encoder
-      .getDecodedBuffer({
-        width: 512,
-        height: 512,
-        bitsPerSample: 16,
-        componentCount: 1,
-      })
-      .set(ct2Raw)
-    encoder.setNearLossless(0)
-    encoder.encode()
-    encoder.delete()
+  bench("encode CT2.RAW (lossless near=0) — kernel", () => {
+    encCT2.encode()
   })
 })

packages/libjpeg-turbo-8bit/bench/decode.bench.js

@@ -1,3 +1,8 @@
+// Decoder/encoder construction is hoisted to module scope so the bench
+// body only measures the decode/encode kernel itself. A separate
+// "instantiate+destroy" bench measures the lifecycle cost that the old
+// monolithic bench was conflating with kernel time.
+
 import { bench, describe } from "vitest"
 import { existsSync, readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
@@ -18,31 +23,43 @@ const rawDecoded = !skip
   : null
 
 let codec
+let dec
+let enc
 if (!skip) {
   const factory = (await import(distPath)).default ?? (await import(distPath))
   codec = await factory()
+
+  dec = new codec.JPEGDecoder()
+  dec.getEncodedBuffer(jpegEncoded.length).set(jpegEncoded)
+
+  enc = new codec.JPEGEncoder()
+  enc
+    .getDecodedBuffer({
+      width: 600,
+      height: 800,
+      bitsPerSample: 8,
+      componentCount: 1,
+      isSigned: false,
+    })
+    .set(rawDecoded)
 }
 
 describe.skipIf(skip)("libjpeg-turbo-8bit (wasm)", () => {
-  bench("decode jpeg400jfif.jpg (600x800x8bit)", () => {
-    const decoder = new codec.JPEGDecoder()
-    decoder.getEncodedBuffer(jpegEncoded.length).set(jpegEncoded)
-    decoder.decode()
-    decoder.delete()
+  bench("instantiate+destroy JPEGDecoder", () => {
+    const d = new codec.JPEGDecoder()
+    d.delete()
+  })
+
+  bench("instantiate+destroy JPEGEncoder", () => {
+    const e = new codec.JPEGEncoder()
+    e.delete()
+  })
+
+  bench("decode jpeg400jfif.jpg (600x800x8bit) — kernel", () => {
+    dec.decode()
   })
 
-  bench("encode raw 600x800x8bit (lossy default)", () => {
-    const encoder = new codec.JPEGEncoder()
-    encoder
-      .getDecodedBuffer({
-        width: 600,
-        height: 800,
-        bitsPerSample: 8,
-        componentCount: 1,
-        isSigned: false,
-      })
-      .set(rawDecoded)
-    encoder.encode()
-    encoder.delete()
+  bench("encode raw 600x800x8bit (lossy default) — kernel", () => {
+    enc.encode()
   })
 })

packages/openjpeg/bench/decode.bench.js

@@ -1,3 +1,13 @@
+// Decoder/encoder construction is hoisted to module scope so the bench
+// body only measures the decode/encode kernel itself. Each fixture gets
+// its own pre-constructed instance because the underlying wasm
+// J2KDecoder advances internal state on decode() and can't be reused
+// across multiple bench bodies. A separate "instantiate+destroy" bench
+// measures the lifecycle cost that the old monolithic bench was
+// conflating with kernel time — the openjpeg encode CT1.RAW bench had
+// the worst variance in the suite (110% spread across 3 runs) and this
+// split is the fix.
+
 import { bench, describe } from "vitest"
 import { existsSync, readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
@@ -18,45 +28,59 @@ const ctLossy = !skip
   : null
 
 let codec
+let decCT1
+let decCT2
+let decLossy
+let encCT1
 if (!skip) {
   const factory = (await import(distPath)).default ?? (await import(distPath))
   codec = await factory()
+
+  decCT1 = new codec.J2KDecoder()
+  decCT1.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
+
+  decCT2 = new codec.J2KDecoder()
+  decCT2.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
+
+  decLossy = new codec.J2KDecoder()
+  decLossy.getEncodedBuffer(ctLossy.length).set(ctLossy)
+
+  encCT1 = new codec.J2KEncoder()
+  encCT1
+    .getDecodedBuffer({
+      width: 512,
+      height: 512,
+      bitsPerSample: 16,
+      componentCount: 1,
+      isSigned: true,
+    })
+    .set(ct1Raw)
 }
 
 describe.skipIf(skip)("openjpeg J2K (wasm)", () => {
-  bench("decode CT1.j2k (.90 lossless 5-3, 512x512x16bit)", () => {
-    const decoder = new codec.J2KDecoder()
-    decoder.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("instantiate+destroy J2KDecoder", () => {
+    const d = new codec.J2KDecoder()
+    d.delete()
+  })
+
+  bench("instantiate+destroy J2KEncoder", () => {
+    const e = new codec.J2KEncoder()
+    e.delete()
+  })
+
+  bench("decode CT1.j2k (.90 lossless 5-3, 512x512x16bit) — kernel", () => {
+    decCT1.decode()
   })
 
-  bench("decode CT2.j2k (.90 lossless 5-3, 512x512x16bit)", () => {
-    const decoder = new codec.J2KDecoder()
-    decoder.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("decode CT2.j2k (.90 lossless 5-3, 512x512x16bit) — kernel", () => {
+    decCT2.decode()
   })
 
-  bench("decode CT-512x512-lossy.j2k (.91 irreversible 9-7)", () => {
-    const decoder = new codec.J2KDecoder()
-    decoder.getEncodedBuffer(ctLossy.length).set(ctLossy)
-    decoder.decode()
-    decoder.delete()
+  bench("decode CT-512x512-lossy.j2k (.91 irreversible 9-7) — kernel", () => {
+    decLossy.decode()
   })
 
-  bench("encode CT1.RAW (lossless)", () => {
-    const encoder = new codec.J2KEncoder()
-    encoder
-      .getDecodedBuffer({
-        width: 512,
-        height: 512,
-        bitsPerSample: 16,
-        componentCount: 1,
-        isSigned: true,
-      })
-      .set(ct1Raw)
-    encoder.encode()
-    encoder.delete()
+  bench("encode CT1.RAW (lossless) — kernel", () => {
+    encCT1.encode()
   })
 })

packages/openjphjs/bench/decode.bench.js

@@ -1,3 +1,8 @@
+// Decoder/encoder construction is hoisted to module scope so the bench
+// body only measures the decode/encode kernel itself. A separate
+// "instantiate+destroy" bench measures the lifecycle cost that the old
+// monolithic bench was conflating with kernel time.
+
 import { bench, describe } from "vitest"
 import { existsSync, readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
@@ -15,39 +20,52 @@ const ct2Encoded = !skip ? readFileSync(resolve(fixturesDir, "j2c/CT2.j2c")) : n
 const ct1Raw = !skip ? readFileSync(resolve(fixturesDir, "raw/CT1.RAW")) : null
 
 let codec
+let decCT1
+let decCT2
+let encCT1
 if (!skip) {
   const factory = (await import(distPath)).default ?? (await import(distPath))
   codec = await factory()
+
+  decCT1 = new codec.HTJ2KDecoder()
+  decCT1.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
+
+  decCT2 = new codec.HTJ2KDecoder()
+  decCT2.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
+
+  encCT1 = new codec.HTJ2KEncoder()
+  encCT1
+    .getDecodedBuffer({
+      width: 512,
+      height: 512,
+      bitsPerSample: 16,
+      componentCount: 1,
+      isSigned: true,
+      isUsingColorTransform: false,
+    })
+    .set(ct1Raw)
 }
 
 describe.skipIf(skip)("openjphjs HTJ2K (wasm)", () => {
-  bench("decode CT1.j2c (.201 lossless, 512x512x16bit)", () => {
-    const decoder = new codec.HTJ2KDecoder()
-    decoder.getEncodedBuffer(ct1Encoded.length).set(ct1Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("instantiate+destroy HTJ2KDecoder", () => {
+    const d = new codec.HTJ2KDecoder()
+    d.delete()
+  })
+
+  bench("instantiate+destroy HTJ2KEncoder", () => {
+    const e = new codec.HTJ2KEncoder()
+    e.delete()
+  })
+
+  bench("decode CT1.j2c (.201 lossless, 512x512x16bit) — kernel", () => {
+    decCT1.decode()
   })
 
-  bench("decode CT2.j2c (.201 lossless, 512x512x16bit)", () => {
-    const decoder = new codec.HTJ2KDecoder()
-    decoder.getEncodedBuffer(ct2Encoded.length).set(ct2Encoded)
-    decoder.decode()
-    decoder.delete()
+  bench("decode CT2.j2c (.201 lossless, 512x512x16bit) — kernel", () => {
+    decCT2.decode()
   })
 
-  bench("encode CT1.RAW (HTJ2K lossless)", () => {
-    const encoder = new codec.HTJ2KEncoder()
-    encoder
-      .getDecodedBuffer({
-        width: 512,
-        height: 512,
-        bitsPerSample: 16,
-        componentCount: 1,
-        isSigned: true,
-        isUsingColorTransform: false,
-      })
-      .set(ct1Raw)
-    encoder.encode()
-    encoder.delete()
+  bench("encode CT1.RAW (HTJ2K lossless) — kernel", () => {
+    encCT1.encode()
   })
 })