runtime: expose Atomics operations for SharedArrayBuffer views

[andrewtdiz]

Summary

Node exposes the global Atomics object for operations on integer typed-array views over SharedArrayBuffer. Perry has ArrayBuffer, SharedArrayBuffer, and DataView constructor support, but source search found no Atomics global or runtime operations.

Expected Node behavior

Local Node v25.9.0 probe:

console.log(typeof SharedArrayBuffer); // "function"
console.log(typeof Atomics);           // "object"

const sab = new SharedArrayBuffer(4);
const ia = new Int32Array(sab);
console.log(Atomics.add(ia, 0, 5)); // 0
console.log(ia[0]);                 // 5
console.log(Atomics.load(ia, 0));   // 5

The standard surface includes methods such as load, store, add, sub, and, or, xor, exchange, compareExchange, wait, notify, and related validation behavior.

Current Perry behavior in source

docs/typescript-parity-gaps.md still calls out SharedArrayBuffer / Atomics as a missing thread/shared-memory area.

Current source has substantial ArrayBuffer / SharedArrayBuffer / DataView support:

• crates/perry-runtime/src/object/global_this.rs lists ArrayBuffer, SharedArrayBuffer, and DataView constructors.
• crates/perry-codegen/src/lower_call/builtin.rs lowers new ArrayBuffer(...), new SharedArrayBuffer(...), and new DataView(...).
• crates/perry-runtime/src/buffer/from.rs implements the backing storage helpers.

But source search found no Atomics entry in global_this.rs, no HIR/codegen lowering, and no runtime methods for atomic operations. That leaves SharedArrayBuffer without the Node-compatible synchronization API that normally accompanies it.

Suggested tests

Start with deterministic single-thread semantics:

expect(typeof Atomics).toBe("object");
const sab = new SharedArrayBuffer(8);
const i32 = new Int32Array(sab);
expect(Atomics.load(i32, 0)).toBe(0);
expect(Atomics.store(i32, 0, 7)).toBe(7);
expect(Atomics.add(i32, 0, 5)).toBe(7);
expect(Atomics.load(i32, 0)).toBe(12);
expect(Atomics.compareExchange(i32, 0, 12, 99)).toBe(12);
expect(Atomics.load(i32, 0)).toBe(99);

Also cover TypeError/RangeError validation for non-shared views, unsupported element types, and out-of-bounds indexes.

Scope / non-goals

This is scoped to exposing the global Atomics object and core operations for integer typed-array views over SharedArrayBuffer. Cross-thread wait/notify scheduling may need a separate implementation phase, but the object and deterministic operations should still have Node-compatible behavior.

[andrewtdiz]

Opened focused first-slice draft PR for the deterministic numeric integer TypedArray operations: #4247

Scope covered: global Atomics, load, store, add, sub, exchange, and compareExchange on numeric integer TypedArray views. wait/notify, BigInt Atomics, and deeper shared-memory aliasing remain out of scope for this cut.

Validation run:

• Node oracle with node@25 --experimental-strip-types
• focused parity: node-suite/globals/atomics-basic PASS
• targeted cargo check for runtime/HIR/codegen
• cargo fmt --all -- --check
• git diff --check
• ./scripts/check_file_size.sh

[andrewtdiz]

Claiming a narrow follow-up slice for numeric integer TypedArray Atomics: add Atomics.and, Atomics.or, and Atomics.xor parity coverage and runtime/codegen support. I will keep wait/waitAsync/notify, BigInt Atomics, and deeper shared-memory aliasing out of scope.

[andrewtdiz]

Opened draft PR #4253 for the next scoped Atomics slice: #4253

This adds numeric TypedArray support for Atomics.and, Atomics.or, and Atomics.xor, including Perry's Buffer-backed Uint8Array receiver path, with a focused globals parity fixture. wait/waitAsync/notify, BigInt Atomics, and full shared-memory aliasing remain out of scope for this cut.

[andrewtdiz]

Claiming the next scoped Atomics slice: add Atomics.isLockFree, Atomics.notify, and deterministic nonblocking Atomics.wait behavior for numeric Int32Array SharedArrayBuffer views.

Planned coverage: method presence/lengths, isLockFree size results, notify returning 0 when no waiters, wait returning not-equal and zero-timeout timed-out, plus focused validation for unsupported wait receiver kinds. Non-goals: full cross-thread waiter queue scheduling, waitAsync, and BigInt Atomics.

[andrewtdiz]

Opened draft PR #4257 for the next deterministic Atomics slice: #4257

Scope in this cut:

• Add Atomics.isLockFree, Atomics.notify, and deterministic nonblocking Atomics.wait runtime entry points for Int32 typed-array views.
• Wire those methods through static-call lowering, FFI declarations, namespace installation, typeof recognition, and .length metadata.
• Add a Node-suite fixture for method presence/lengths, lock-free size results, immediate wait returns (not-equal, timed-out), no-waiter notify, Int32-only validation, and index range errors.

Still out of scope: full waiter queues, waitAsync, and BigInt Atomics.

Validation completed:

• Node v26 oracle for test-parity/node-suite/globals/atomics-wait-notify.ts
• cargo check -p perry-runtime -p perry-codegen -p perry-hir
• cargo fmt --all -- --check
• git diff --cached --check
• ./scripts/check_file_size.sh

Local parity-runner note: the focused parity runner release build was terminated before fixture execution, and a follow-up debug binary build was also terminated before producing target/debug/perry, so I could not complete a local Perry-vs-Node fixture diff in this environment.

[andrewtdiz]

Claiming the next scoped Atomics slice: BigInt typed-array operations for BigInt64Array and BigUint64Array.

Planned scope:

• make Atomics.load, store, add, sub, and, or, xor, exchange, and compareExchange return/consume BigInt values for BigInt64Array/BigUint64Array receivers;
• preserve existing numeric integer TypedArray behavior from the merged basic/bitwise Atomics cuts;
• add focused Node parity coverage for signed/unsigned 64-bit wraparound, compareExchange equality, bitwise operations, and Number-vs-BigInt validation.

Non-goals: full waiter queues, waitAsync, BigInt wait/notify behavior, and deeper shared-memory aliasing beyond the current typed-array storage model.

[andrewtdiz]

Opened draft PR #4278 for the BigInt typed-array Atomics slice: #4278

Scope covered there: Atomics.load, store, add, sub, and, or, xor, exchange, and compareExchange on BigInt64Array / BigUint64Array, with BigInt return values, 64-bit wrapping, compareExchange matching, and Number-vs-BigInt coercion parity.

[andrewtdiz]

Opened draft PR #4278 for the BigInt typed-array Atomics slice: #4278

Scope covered in this PR:

• BigInt64Array / BigUint64Array support for Atomics.load, store, add, sub, and, or, xor, exchange, and compareExchange
• full 64-bit signed/unsigned wrapping and BigInt return types
• BigInt/Number operand validation while preserving the existing numeric integer typed-array path
• new globals parity fixture covering signed/unsigned wrap, 64-bit bitwise behavior, compareExchange, and coercion errors

Validation passed:

• cargo check -p perry-runtime -p perry-codegen -p perry-hir
• release build for perry, perry-runtime, and perry-stdlib
• run_parity_tests.sh --suite node-suite --module globals --filter atomics (3/3 pass)
• cargo fmt --all -- --check
• git diff --check
• ./scripts/check_file_size.sh

Still out of scope here: Atomics.wait, waitAsync, notify, wait queue behavior, and broader shared-memory/inter-thread semantics.