Shared Array Loading

## The problem `SharedArray` solves Every k6 virtual user is a **separate JavaScript runtime**. Whatever the init code allocates, it allocates once per VU. Parse a 50,000-row user list with `JSON.parse(open('./users-50k.json'))` at module scope and a 200-VU run holds 200 independent parsed copies of those 50,000 rows on 200 separate JS heaps. The rows are identical in all of them, and no VU can see any other VU's copy. `SharedArray`, the single export of the built-in `k6/data` module, removes that multiplication. The data is produced once, marshalled once and stored once for the whole k6 process; each VU is handed a lightweight array-like wrapper over that one copy. ## The constructor ```javascript import { SharedArray } from 'k6/data'; const users = new SharedArray('users', function () { return JSON.parse(open('./users-50k.json')); // must return an array }); ``` Three parts of that call are load-bearing: 1. **It must run in the init context** — at module scope, before `setup()` or the default function. Constructing one later throws `new SharedArray must be called in the init context`. 2. **The first argument is a non-empty name.** VUs are separate runtimes, so the name — not the variable — is the identity. k6 keeps one process-wide map from name to data. 3. **The second argument is a plain, non-`async` function that returns an array.** k6 calls it at most once per name, no matter how many VUs reach that line. ## Where the data actually lives k6 does not keep the JavaScript array the loader returned. It walks it, runs `JSON.stringify()` on **each element**, and keeps the resulting strings. The shared copy therefore lives as a list of JSON texts held by the k6 process itself, outside every VU's JavaScript heap. That single implementation choice explains every other behaviour of the type. Two things follow immediately. The shared set occupies no JavaScript heap in any VU, so adding VUs does not add copies of it; and whatever the loader returned has already been flattened to text, so the array k6 keeps is emphatically not the array your loader built. ## What an element access costs Reading `users[i]` is not a pointer dereference. k6 takes the stored string for element `i`, runs `JSON.parse()` on it, deep-freezes the result and hands the VU that fresh value. The consequences: - Each read produces a **new object**, so `users[0] === users[0]` is `false`. - The copy is per-iteration garbage; it never grows the shared set. - An out-of-range index returns `undefined` rather than throwing. - `length`, index access, `for...of` and `forEach()` all work — the wrapper really is an array, and `Array.isArray(users)` is `true`. - Nothing is cached between reads, so an iteration needing the same row twice should hold it in a local variable. - The price is **CPU per access**, not memory: you pay a small parse in exchange for copies you no longer hold. | holding 50,000 rows | `const rows = JSON.parse(open(...))` | `new SharedArray('rows', ...)` | |---|---|---| | copies in memory | one per VU | one per k6 process | | when the parsing happens | once per VU, during init | once per name, during init | | cost of `rows[i]` | a plain property read | one `JSON.parse` of that element | | writable? | yes | no — throws `TypeError: SharedArray is immutable` | | usable to pass data between VUs? | no | no — read-only by design | ## When the trade pays off The saving scales with the size of the set and the number of VUs; the parse cost scales with how often each iteration reads. k6's own documentation reports that below roughly a thousand elements the memory benefit is small enough that the per-access parse can dominate, while from around ten thousand elements upward the saving becomes decisive. A 50,000-row user list read once or twice per iteration sits squarely in the range `SharedArray` was built for; a five-row lookup table hammered in a tight inner loop does not. ## What `SharedArray` is not It is **not** a communication channel. Once built it is read-only for the life of the test and there is no write path at all, so one VU cannot leave anything in it for another. It is also the wrong home for a single large object: wrapping one big configuration blob in a one-element array leaves you with a single stored JSON string that must be parsed in full on every access — the parse cost without the per-element granularity that makes the trade worth taking. And it is not a lazy view of a file: the loader runs to completion during init, so whatever it returned is fixed for the whole run, and a later change on disk is invisible to the test.