Run large full cycle-collector passes on idle CPUs in speed builds

docs/content/docs/cli.mdx

@@ -103,7 +103,7 @@ Verifies and reads the installed precompiled runtime objects and vendor archives
   <dd>Remove symbol and debug payload when linking an executable, including cross-compiled targets. This flag preserves code optimization.</dd>
 
   <dt><code>--optimization &lt;release|dev|speed&gt;</code></dt>
-  <dd>Select native optimization for executable, assembly, or object output. The default is <code>release</code> (<code>-O2</code>). <code>dev</code> uses <code>-O0</code> and emits source locations for TypeScript and JavaScript breakpoints and stack frames. LLVM builds include source variable names and native storage descriptions; see <a href="/limitations#native-debugging">Native debugging</a> for the supported representations. macOS executable builds also produce an adjacent <code>.dSYM</code> bundle. <code>speed</code> is <code>-O2</code> plus optimizations that trade binary size and build time for run-time speed: it lets LLVM inline small runtime functions into program code, emits reference counting inline, and on x86-64 starts every runtime function on a cache-line boundary. Expect larger executables and longer cold builds than <code>release</code>; how much faster a program runs depends on how much of its time is spent in the runtime. Runtime inlining needs a runtime pack built with the LLVM helper; where a runtime pack lacks it, <code>speed</code> links the release runtime and keeps inline reference counting. Selecting <code>speed</code> never changes what <code>release</code> builds produce, and the two never share cached artifacts. Library profiles accept <code>"optimization": "speed"</code> for inline reference counting.</dd>
+  <dd>Select native optimization for executable, assembly, or object output. The default is <code>release</code> (<code>-O2</code>). <code>dev</code> uses <code>-O0</code> and emits source locations for TypeScript and JavaScript breakpoints and stack frames. LLVM builds include source variable names and native storage descriptions; see <a href="/limitations#native-debugging">Native debugging</a> for the supported representations. macOS executable builds also produce an adjacent <code>.dSYM</code> bundle. <code>speed</code> is <code>-O2</code> plus optimizations that trade binary size and build time for run-time speed: it lets LLVM inline small runtime functions into program code, emits reference counting inline, on x86-64 starts every runtime function on a cache-line boundary, and on Linux and macOS lets large cycle-collector passes mark on idle CPUs (<code>SCR_CYCLE_PARALLEL=0</code> turns that off). Expect larger executables and longer cold builds than <code>release</code>; how much faster a program runs depends on how much of its time is spent in the runtime. Runtime inlining needs a runtime pack built with the LLVM helper; where a runtime pack lacks it, <code>speed</code> links the release runtime and keeps inline reference counting. Selecting <code>speed</code> never changes what <code>release</code> builds produce, and the two never share cached artifacts. Library profiles accept <code>"optimization": "speed"</code> for inline reference counting.</dd>
 
   <dt><code>--windows-subsystem &lt;console|gui&gt;</code></dt>
   <dd>Select the subsystem of a Windows executable. <code>console</code> is the default; <code>gui</code> prevents Windows from opening a console window for the app. Valid only for executable builds targeting Windows.</dd>

packages/runtime-darwin-arm64/scripts/build.mjs

@@ -141,12 +141,21 @@ async function build() {
     const flavors = {};
     // The executable `speed` flavor (--optimization=speed) exists only when
     // it differs from release: its static units are emitted through the host
-    // LLVM helper with import bitcode. Its SCR_DYNAMIC variants are the
-    // release objects themselves.
+    // LLVM helper with import bitcode, and SCR_SPEED selects runtime code that
+    // trades size for speed (parallel cycle-collector passes). Its
+    // SCR_DYNAMIC variants are the release objects themselves.
     const flavorPlan = [
       ...Object.entries(RUNTIME_PACK_MATRIX.flavors),
       ...("release" in RUNTIME_PACK_MATRIX.flavors && unitHelper !== null
-        ? [["speed", RUNTIME_PACK_MATRIX.flavors.release]]
+        ? [
+            [
+              "speed",
+              {
+                ...RUNTIME_PACK_MATRIX.flavors.release,
+                defines: [...(RUNTIME_PACK_MATRIX.flavors.release.defines ?? []), "SCR_SPEED"],
+              },
+            ],
+          ]
         : []),
     ];
     const releaseVariants = new Map();

packages/runtime-pack-common/scripts/build.mjs

@@ -175,12 +175,21 @@ async function build() {
     const flavors = {};
     // The executable `speed` flavor (--optimization=speed) exists only when
     // it differs from release: its static units are emitted through the host
-    // LLVM helper with import bitcode. Its SCR_DYNAMIC variants are the
-    // release objects themselves.
+    // LLVM helper with import bitcode, and SCR_SPEED selects runtime code that
+    // trades size for speed (parallel cycle-collector passes). Its
+    // SCR_DYNAMIC variants are the release objects themselves.
     const flavorPlan = [
       ...Object.entries(matrix.flavors),
       ...("release" in matrix.flavors && unitHelper !== null
-        ? [["speed", matrix.flavors.release]]
+        ? [
+            [
+              "speed",
+              {
+                ...matrix.flavors.release,
+                defines: [...(matrix.flavors.release.defines ?? []), "SCR_SPEED"],
+              },
+            ],
+          ]
         : []),
     ];
     const releaseVariants = new Map();