Share
Embed
How I Made V8's Array.prototype.flat Up to 20× Faster—and the Journey to a Large-Scale OSS Contribution
This slide was created with Slidev and is available in the following repository:
https://github.com/riya-amemiya/amemiya_riya_slide_data/tree/main/v8_array_flat-en
View the animated version here:
https://riya-amemiya.github.io/amemiya_riya_slide_data/v8_array_flat-en/
Riya Amemiya
November 22, 2026
Transcript
68 slides
-
Making V8's Array.prototype.flat up to ~20x faster, and the road
to a large commit in a huge OSS project Yuta Nishi / Dinii Inc. -
About me Yuta Nishi 21 years old (important) V8 Contributor
Platform Engineer at Dinii Inc. TSKaigi Staff I love TypeScript I also love sending patches to V8 And I love baseball @riya-amemiya -
Why I sent this patch in the first place One
day, a post saying "JSC's Array.prototype.flat is getting faster" showed up on my X timeline Reading the implementation, it looked like the same idea could apply to V8 About a month later, my patch was merged into V8 14.7 -
This patch is not in Node.js 26 yet ❯ node
-v v26.13.1 ❯ node -p process.versions.v8 14.6.202.34-node.40 -
flat gets faster starting with Node.js 27 ❯ node -v
v27.0.0-alpha.0.1.1 ❯ node -p process.versions.v8 15.6.75.50-node.14 -
In Chrome, Node.js, Deno, and every runtime that ships V8,
flat becomes up to ~20x faster -
~20x in two steps Up to ~5x with the two-pass
patch, then another ~5x with the bulk copy patch that followed Before Two-pass Bulk copy 1x ~5x, since V8 14.7 ~20x, since V8 15.1 -
This talk is mostly about the optimization Why the old
flat was slow The two-pass approach that cuts memory allocation down to one The struggle with flat’s rule of compacting holes Skipping the traversal itself with ElementsKind Another ~5x with bulk copy The implementation in Torque, V8’s own language I will walk through these in order I will also show the path from a proposal on v8-dev through Gerrit review to the merge, and the fight with ClusterFuzz the day after -
Understanding the spec of flat > [[1, 2], [3, 4]].flat()
[ 1, 2, 3, 4 ] > [[[1]], [[2]]].flat(2) [ 1, 2 ] Returns a new array flattened depth levels deep depth defaults to 1 -
The old implementation of flat The flow Create an empty
array What a reallocation does ↓ Read one element of the source array ↓ If it is an array, recurse into it ↓ Otherwise append it to the result through a generic property store every time ↓ When capacity runs out, reallocate and copy ↑ Repeat for every element Allocate an array with the new capacity ↓ Copy everything from the old array -
Before Done Input is 6 sub-arrays of 10 elements Result
array capacity is 82 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 Allocations 3 Writes 60 Re-copied 60 Recursive calls 6 New capacity = required length + half of the required length + 16 -
Before and the two-pass approach Before Create an empty array
Two-pass ↓ Look at elements one by one recurse into arrays ↓ Pass 1 finds the length and type ↓ Allocate once with that length ↓ Pass 2 writes directly Append one to the end of the result ↓ When capacity runs out reallocate and copy ↑ Repeat for every element Based on the two-pass approach Sosuke Suzuki implemented in JSC https://github.com/WebKit/WebKit/pull/56035 -
How many times the result array is allocated To start,
6 sub-arrays of 10 elements that hold only numbers Before Allocate capacity 17 Reallocate to 43 and copy 17 Reallocate to 82 and copy 43 Two-pass Allocate capacity 60 only once -
Before and two-pass, side by side Before Input is 6
sub-arrays of 10 elements Done Allocations 3 Writes 60 Re-copied 60 Recursive calls 6 Two-pass Allocations 1 Writes 60 Checks 240 Done -
What a hole is In a JavaScript array, an index
with no element is called a hole [1, , 3] 1 hole 3 [1, undefined, 3] 1 undefined 3 Unlike undefined , a hole has no property at all -
How holes are handled map keeps holes 1 hole flat
skips holes and compacts 3 ↓ map(n => n * 2) 2 hole 1 hole ↓ flat() 6 1 3 3 -
The tricky part for the optimization The source .length is
5 1 hole 3 hole 5 ↓ flat() The result length is 3 1 3 5 To know the length up front, holes have to be left out of the count -
V8 code shows up from here, so here are four
terms first Torque A language dedicated to writing V8's builtins fast path A fast route taken only when conditions hold slow path The existing route that is correct for any input bailout Switching to the slow path when an assumption breaks -
Counting an array with holes Look at elements one by
one and count everything except holes // src/builtins/array-flat.tq let element: JSAny; try { element = fastOW.LoadElementNoHole(index) otherwise FoundHole; } label FoundHole { index++; continue; } LoadElementNoHole jumps to FoundHole when it finds a hole Torque's otherwise names where to jump on an early exit -
Compacting holes Done Input array has .length 10 1 hole
3 4 hole 6 8 9 hole Result array capacity is 6 1 3 4 6 Allocations 1 Writes 6 Skipped holes 4 8 9 hole -
The cost of pass 1 The two-pass approach walks the
array twice, so pass 1 should be cheap Count every element Look at the kind of array Pass 1 looks at every element and counts For numeric arrays, only look at the kind and .length Allocate once with that length Allocate once with that length Pass 2 writes every element Pass 2 writes every element ↓ ↓ ↓ ↓ -
What ElementsKind is V8 tracks the contents of an array
with internal types such as "integers only", "contains floating-point numbers", or "has holes" called ElementsKind With this type information it becomes obvious that "an array that contains only numbers cannot contain sub-arrays", so the traversal itself can be skipped -
The main ElementsKinds Small integers (Smi) only Contains floating-point numbers
Contains strings or objects Packed (no holes) Holey (has holes) PACKED_SMI_ELEMENTS HOLEY_SMI_ELEMENTS [1, 2, 3] [1, , 3] PACKED_DOUBLE_ELEMENTS HOLEY_DOUBLE_ELEMENTS [1, 2.5, 3] [1.5, , 3] PACKED_ELEMENTS HOLEY_ELEMENTS [1, "a", {}] [1, , "a"] PACKED_SMI_ELEMENTS and PACKED_DOUBLE_ELEMENTS never hold sub-arrays, Proxies, or holes The optimization relies on this guarantee -
A shortcut for numeric arrays Numbers only and no holes
is guaranteed, so there is no need to look at each element [1, 2, 3, 4, 5] is PACKED_SMI_ELEMENTS 1 2 3 4 ↓ use .length as is, without looking at elements The result length is 5 5 -
If the source is PACKED_SMI_ELEMENTS or PACKED_DOUBLE_ELEMENTS .length becomes the
result length as is // src/builtins/array-flat.tq if (sourceKind == ElementsKind::PACKED_SMI_ELEMENTS || sourceKind == ElementsKind::PACKED_DOUBLE_ELEMENTS) { return FlattenedLengthResult{length: sourceLength, targetKind: sourceKind}; } Computing the length of [1, 2, 3, ..., 1024].flat() is O(1) -
[[1,2,3], [4,5,6], [7,8,9]].flat() For numeric sub-arrays, add .length without reading
their contents The outer array is PACKED_ELEMENTS 1 2 3 PACKED_SMI, so +3 The result length is 9 4 5 6 PACKED_SMI, so +3 7 8 9 PACKED_SMI, so +3 -
Arrays of mixed types Along with the length, pass 1
also decides the ElementsKind of the result array For [[1, 2], [3.5], ["a", "b"]].flat() Before PACKED_SMI When 3.5 arrives reallocate and copy → PACKED_DOUBLE PACKED_ELEMENTS allocated only once Two-pass Pass 1 checks every type → When "a" arrives reallocate and copy → PACKED_ELEMENTS -
Arrays of mixed types Done Input is [[1, 2], [3.5],
["a", "b"]] Before PACKED_ELEMENTS 1 2 3.5 "a" "b" Allocations 3 Re-copied 5 Two-pass PACKED_ELEMENTS 1 2 3.5 "a" "b" Allocations 1 Re-copied 0 -
The ElementsKind of the result array While counting the length,
track the type of values going into the result with three flags // src/builtins/array-flat.tq if (!IsNumber(element)) { seenObject = true; } else if (!TaggedIsSmi(element)) { seenDouble = true; } else { seenSmi = true; } The result of [[1], [2], [3]].flat() is PACKED_SMI_ELEMENTS -
Pass 2 still copied one at a time Pass 2
of the two-pass approach Step into the sub-array Read one element ↓ ↓ Four checks shape change, hole, Proxy, write bounds ↓ Write one to the result ↑ Repeat for every element Bulk copy Check the sub-array type only once ↓ Copy everything at once with memcpy -
Numeric sub-arrays are copied in one go Pass 1 has
already fixed the length and type, so the block can be poured in as is Memory of sub-array [1, 2, 3] 1 2 3 ↓ memcpy copies all 3 at once Memory of the result array 0 1 2 3 HOLEY sub-arrays cannot be memcpy'd and are copied one by one -
Two-pass and bulk copy, side by side Two-pass Input is
6 sub-arrays of 10 elements Done Allocations 1 Writes 60 Checks 240 Bulk copy Allocations 1 memcpy 6 Checks 6 Done -
TorqueCopyElements ends up calling memcpy from libc // src/builtins/array-flat.tq if
(subArray.map.elements_kind == ElementsKind::PACKED_SMI_ELEMENTS) { const srcElements: FixedArray = Cast<FixedArray>(subArray.elements) otherwise goto Bailout; const srcLen: Smi = Cast<Smi>(subArray.length) otherwise goto Bailout; const newIdx: Smi = math::TrySmiAdd(targetIndex, srcLen) otherwise goto Bailout; if (Convert<intptr>(newIdx) > vector.fixedArray.length_intptr) { goto Bailout; } TorqueCopyElements( vector.fixedArray, SmiUntag(targetIndex), srcElements, 0, SmiUntag(srcLen)); targetIndex = newIdx; index++; continue; } PACKED_DOUBLE_ELEMENTS copies its FixedDoubleArray the same way -
Only numeric arrays can be memcpy’d ElementsKind Contents Pointers memcpy
PACKED_SMI_ELEMENTS The small integers themselves None Yes PACKED_DOUBLE_ELEMENTS Raw doubles None Yes PACKED_ELEMENTS References to strings and objects Yes No The dividing line is the write barrier -
Write barrier V8's GC needs to know which object points
where The write barrier is what tells the GC every time a pointer is written Writing one at a time Write one pointer Copying in one go with memcpy ↓ The write barrier tells the GC ↑ Repeat for every element Copy the pointers all at once ↓ The GC never learns about the new references ↓ Live objects get collected and you get a use-after-free -
Copying sub-arrays into the result Done PACKED_SMI_ELEMENTS 1 2 3
4 5 → 1 2 3 4 5 GC notifications 0 PACKED_ELEMENTS obj obj obj obj obj → obj obj obj obj obj GC notifications 5 -
Allocating without initialization In the same CL as bulk copy,
the allocation for a FixedDoubleArray result changed too Two-pass Bulk copy Allocate with Allocate with the uninitialized AllocateFixedDoubleArrayWithHoles AllocateFixedArray Fill every slot with the hole value so unwritten slots never read garbage Use it as a FixedDoubleArray ↓ ↓ ↓ ↓ Pass 2 writes every slot Pass 2 writes every slot Pass 1 counts the length exactly, so pass 2 always fills every slot -
The old flat is Torque’s FlattenIntoArrayFast and FlattenIntoArraySlow TryFastFlat is
added in front of them // src/builtins/array-flat.tq try { return TryFastFlat(o, len, depthSmi) otherwise SlowFastPath; } label SlowFastPath {} const a: JSReceiver = ArraySpeciesCreate(context, o, 0); If the conditions are not met, it falls through to the existing slow path -
Where it bails out Stay on the fast path while
the assumptions hold, and switch to the slow path on the spot when they break Where What is checked Fast path entry The length fits in a Smi, the array is in fast mode, Symbol.species is the default During the traversal Recheck() confirms the array’s shape has not changed, and there is no Proxy End of pass 2 The number of written elements matches the length counted in pass 1 Fast mode means an array whose ElementsKind is one of the six PACKED or HOLEY kinds and whose prototype chain is still the default -
The whole flow before the optimization Create an empty array
→ Read an element → Recurse into arrays → Append one to the end → Reallocate when full Shape change 24 hole 24 Is array 3 Capacity 20 Steps Checks Input is [[1, …, 7], [8, , 10, …, 14], [15, …, 21]] 1 2 3 4 5 6 7 8 hole PACKED_SMI 10 11 12 13 14 15 16 HOLEY_SMI 17 18 19 PACKED_SMI Result array capacity is 43 1 2 3 4 5 6 7 8 10 11 12 13 14 15 16 17 18 Allocations 2 Re-copied 17 Writes 20 Recursive calls 3 19 20 21 20 21 Done -
The whole flow after the optimization Check entry → Pass
1 finds length and type → Allocate once → Pass 2 writes → Verify count Steps Checks Entry 1 Shape change 6 hole 20 Is array 6 Write bounds 8 Length match 1 Input is [[1, …, 7], [8, , 10, …, 14], [15, …, 21]] 1 2 3 4 5 6 7 8 hole PACKED_SMI 10 11 12 13 14 15 16 HOLEY_SMI 17 18 19 PACKED_SMI Result array capacity is 20 1 2 3 4 5 6 7 8 10 11 12 Allocations 1 memcpy 2 Writes 6 13 14 15 16 17 18 19 20 21 20 21 Done -
Comparing the three implementations Before Two-pass Bulk copy Result allocation
Rebuilt whenever it runs out Count the length, allocate once Once Sub-array Recurse and append one at Write directly one at a Numeric arrays via memcpy in handling a time time one go Yes Yes Not needed for numeric arrays 1x ~5x ~20x Per-element checks Rough speed -
Benchmark d8 (arm64), V8 14.6.206 compared with main flat(2) on
1,000 sub-arrays of 1,000 elements each Minimum of 8 runs Sub-array type Before After Speedup PACKED_SMI_ELEMENTS 6.09 ms 0.26 ms ~24x PACKED_DOUBLE_ELEMENTS 7.56 ms 0.53 ms ~14x PACKED_ELEMENTS 5.92 ms 3.87 ms ~1.5x HOLEY_SMI_ELEMENTS 5.91 ms 3.45 ms ~1.7x HOLEY_DOUBLE_ELEMENTS 7.49 ms 4.66 ms ~1.6x HOLEY_ELEMENTS 6.12 ms 3.85 ms ~1.6x Without memcpy, non-numeric and HOLEY arrays gain only the single allocation -
Propose on v8-dev and agree on the direction ↓ Upload
a CL to Gerrit Get reviewed and revise ↓ ↓ Get Code-Review+1 from two people ↓ Merge once the Commit-Queue tests pass -
First, propose on v8-dev Do not send a patch out
of the blue for a large change Agree on the direction with reviewers first Post on v8-dev and someone will respond Leszek Swirski's reply "Sounds good, send a patch and let's discuss there" https://groups.google.com/g/v8-dev/c/8ROaTLSDXkM -
The first review comment Leszek: "This fast path should be
implemented in Torque/CSA rather than as a runtime function" First patch set Patch set 2 flat is called flat is called ↓ Call a C++ runtime function every call pays a cost ↓ Enter a fast path written in Torque In V8, fast paths are normally written in Torque or CSA, and only slow paths call the runtime CSA stands for CodeStubAssembler, V8's own assembler for writing builtins -
Getting to the merge Add Leszek, an owner of the
changed files, as a reviewer A merge needs Code-Review+1 from two people I cannot trigger try jobs or the CQ, so I ask the reviewers Label What it does Commit-Queue+1 Only runs the tests on the try bots (dry run) Commit-Queue+2 Merges as soon as the tests pass -
Released in Chrome 147 (V8 14.7) [array] Add Torque fast
path for Array.prototype.flat Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7526287 Reviewed-by: Olivier Flückiger <[email protected]> Reviewed-by: Leszek Swirski <[email protected]> Commit-Queue: Olivier Flückiger <[email protected]> Commit-Queue: Leszek Swirski <[email protected]> Cr-Commit-Position: refs/heads/main@{#105498} -
The day after the merge, Google's automated bug finder ClusterFuzz
found three bugs Emails arrive from buganizer-system crbug 488366773 crbug 488586038 crbug 489008235 -
The cause was that GetPackedElementsKind treated HOLEY_DOUBLE_ELEMENTS as PACKED_DOUBLE_ELEMENTS //
src/builtins/array-flat.tq macro GetPackedElementsKind(kind: ElementsKind): ElementsKind { if (kind == ElementsKind::HOLEY_SMI_ELEMENTS) return ElementsKind::PACKED_SMI_ELEMENTS; if (kind == ElementsKind::HOLEY_DOUBLE_ELEMENTS) return ElementsKind::PACKED_DOUBLE_ELEMENTS; if (kind == ElementsKind::HOLEY_ELEMENTS) return ElementsKind::PACKED_ELEMENTS; return kind; } const sourceKind: ElementsKind = GetPackedElementsKind(source.map.elements_kind); -
Why it crashed A HOLEY_DOUBLE_ELEMENTS array with .length 3 1.5
hole 3.5 ↓ treated as PACKED_DOUBLE_ELEMENTS, so .length 3 is used as the length There are only 2 actual elements 1.5 3.5 The length computed in pass 1 no longer matches the actual number of elements -
Also, with V8_ENABLE_UNDEFINED_DOUBLE a FixedDoubleArray can hold undefined Treated as
PACKED, that undefined was read as a number too // src/builtins/array-flat.tq doubleElements.values[targetIndex] = Convert<float64_or_undefined_or_hole>( UnsafeCast<Number>(element), ); UnsafeCast<Number> in pass 2 receives undefined and crashes -
The fix and the close Delete GetPackedElementsKind and read source.map.elements_kind
directly Take the shortcut only when the array is truly PACKED Add a regression test and put the issue number in the CL’s Bug: line After the merge, ClusterFuzz re-verifies automatically and closes the issues -
Three CLs Two-pass approach, released in Chrome 147 (V8 14.7)
↓ Fix for the crash ClusterFuzz found Bulk copy, since V8 15.1 ↓ -
Summary The optimization The old flat appended one element at
a time while reallocating the result array The two-pass approach finds the length and type first and allocates once Holes are left out of the count in pass 1 and skipped in pass 2 Numeric arrays skip the traversal itself by looking at ElementsKind Numeric sub-arrays need no write barrier, so they are copied in one go with memcpy Implemented as Torque’s TryFastFlat , falling back to the slow path when an assumption breaks Contributing to OSS Agreed on v8-dev, sent to Gerrit, merged with two Code-Review+1 and the CQ The bugs ClusterFuzz found the day after the merge were fixed with a regression test -
References X: x.com/bunjavascript/status/2011898197330075845 WebKit: WebKit/WebKit#56035 v8-dev: [Design/Perf] C++ fast path
for Array.prototype.flat (2-pass, V8) Gerrit: [array] Add Torque fast path for Array.prototype.flat Gerrit: [array] Fix flat fast path crash on HOLEY_DOUBLE with undefined Gerrit: [array] Add bulk copy shortcuts to Array.flat fast path のArray.prototype.flatを最大約5倍高速化した Zenn (Japanese): Chromium(V8)のArray.prototype.flatをバルクコピーでさらに約5倍高速化した Zenn (Japanese): Chromium(V8)