NativeArray

NativeArray — flat numeric arrays for high-performance numeric loops.

Unlike Array (which uses a 32-way persistent trie), NativeArray is backed by a flat OCaml array that maps directly to sequential memory. This makes it cache-friendly for sequential scan patterns and enables tight inner loops for sum, map, and fold operations.

Compiled (--compile) vectorization, in practice:

sum_int / sum_float: both auto-vectorize under clang -O2 (NEON on

  arm64, SSE4.2+ on x86-64) — sum_float needed a scoped
  `#pragma clang fp reassociate(on)` in the runtime C loop, since
  strict IEEE 754 float semantics otherwise block the reduction from
  vectorizing at all.
- map_int with a non-capturing or single-capture lambda: the compiler
  inlines the callback directly into the loop instead of dispatching
  through a closure pointer, which lets clang's own inliner and
  vectorizer see through it — arithmetic-heavy bodies (`fn x -> x*x+1`,
  `fn x -> x + captured`) compile to real SIMD instructions. A closure
  reused elsewhere, or one with more than one captured variable, still
  works correctly but falls back to the slower closure-dispatch path.
- map_float: correct and (for capturing/non-capturing alike) gets the
  same closure-inlining treatment as map_int. Float crossing a
  closure-call boundary is normally heap-boxed (march_alloc_float),
  which blocks vectorization — but when the callback's signature is
  concretely all-Float (no generic type variable), the compiler clones
  the inlined callback under natural double params/return with zero
  boxing, and the loop DOES vectorize (real NEON/SSE, confirmed via
  -emit-llvm). A callback whose signature is still generic at this
  point falls back to the boxed (correct, non-vectorized) path. See
  specs/optimizations.md P10 "Float-boxing Stage 4, Option B" and
  specs/plans/2026-07-13-float-boxing-design.md.
- fold_int / fold_float / fold_f32 / fold_i32 / fold_u8 all have compiled
  implementations: the accumulator crosses the closure boundary in the
  erased/boxed representation (see march_typed_array_fold's RC
  discipline, which native_*_arr_fold mirrors), so no per-width
  vectorization applies — this is a correctness-first scalar loop.
- map2_int / map2_float (two-array zip-with, e.g. for column-column
  arithmetic) get the identical closure-inlining/vectorization treatment
  map_int/map_float do above — same eligibility bar, same unboxed clone
  for a concrete-Float callback. Verified ~47x faster than the pre-fix
  boxed closure-call path on a 5M-element benchmark; see
  docs/simd-benchmarks.md's "Fix history: map2".

Sharing and sending (Part C of specs/plans/2026-09-25-send-data-race-freedom-plan.md): A native array is a VALUE with copy-on-write semantics. set_ and sort_ "return a new array"; the compiled runtime writes in place only when the caller held the sole reference (march_rc_is_unique, an acquire load of the reference count) and copies otherwise, and the interpreter always copies. No program can tell the two apart, so an array may be sent in an actor message, captured by a Task or Parallel closure, or stored in a record like any other value; each holder sees only its own writes. Cost model:

a write to an array nobody else holds is in place: O(1) for set,

  O(n log n) for sort, no allocation;
- the first write to a SHARED array copies it, O(n), one allocation;
  later writes to the copy are in place again;
- sending, capturing in a closure or storing in a record shares the
  array. A loop `let arr = NativeArray.set_int(arr, i, v)` that threads
  the array through never shares it and never copies.
Audited 2026-10-06 (runtime/march_runtime.c): set and sort at all five
widths including the sort fast paths, and the SIMD vector store, are
gated on sole ownership; map/map2 (C and the inlined fast path),
filter_mask, the width conversions and from_list allocate fresh. Nothing
writes an array it does not solely own.

Five opaque element types are supported: NativeIntArr — wraps int array (i64) NativeFloatArr — wraps float array (f64) NativeF32Arr — narrow float array (f32); stores round to nearest-even NativeI32Arr — narrow int array (i32); stores truncate mod 2^32 NativeU8Arr — narrow int array (u8); stores truncate mod 2^8 Narrow-width stores never trap; loads widen exactly (u8 zero-extends, i32 sign-extends). See docs/simd-vectorization.md's "Narrow element widths" section for the full boundary rule and benchmarks.

Usage: let arr = NativeArray.make_float(1000, 0.0) let arr2 = NativeArray.map_float(arr, fn x -> x *. 2.0) let s = NativeArray.sum_float(arr2)

Functions

fnf32_to_float_arrf32_to_float_arr(arr)#

Widen a NativeF32Arr to NativeFloatArr (exact). O(n).

Examples

march> NativeArray.to_list_float(NativeArray.f32_to_float_arr(NativeArray.from_list_f32([0.5, 2.25])))
[0.5, 2.25]

fnfloat_to_f32_arrfloat_to_f32_arr(arr)#

Narrow a NativeFloatArr to a NativeF32Arr, rounding each element to binary32 (nearest-even). O(n).

Examples

march> NativeArray.to_list_f32(NativeArray.float_to_f32_arr(NativeArray.from_list_float([1.5, -0.25])))
[1.5, -0.25]
march> NativeArray.get_f32(NativeArray.float_to_f32_arr(NativeArray.from_list_float([0.1])), 0) == 0.1
false

fnfold_f32fold_f32(arr, acc, f)#

Left fold over all elements (each widened to Float). Argument order: collection first, init second, callback last (uncurried-collection convention). Callback f(acc, elem) = new_acc. O(n).

Examples

march> NativeArray.fold_f32(NativeArray.from_list_f32([0.5, 0.25]), 1.5, fn (acc, x) -> acc +. x)
2.25

fnfold_floatfold_float(arr, acc, f)#

Left fold over all elements. Argument order: collection first, init second, callback last (uncurried-collection convention). Callback f(acc, elem) = new_acc. O(n).

Examples

march> NativeArray.fold_float(NativeArray.from_list_float([1.5, 2.25]), 0.5, fn (acc, x) -> acc +. x)
4.25

fnfold_i32fold_i32(arr, acc, f)#

Left fold over all elements (each sign-extended to Int). Argument order: collection first, init second, callback last (uncurried-collection convention). Callback f(acc, elem) = new_acc. O(n).

Examples

march> NativeArray.fold_i32(NativeArray.from_list_i32([-1, 2]), 10, fn (acc, x) -> acc - x)
9

fnfold_intfold_int(arr, acc, f)#

Left fold over all elements. Argument order: collection first, init second, callback last (uncurried-collection convention). Callback f(acc, elem) = new_acc. O(n).

Examples

march> NativeArray.fold_int(NativeArray.from_list_int([1, 2, 3]), 0, fn (acc, x) -> acc * 10 + x)
123
march> NativeArray.fold_int(NativeArray.from_list_int([]), 5, fn (acc, x) -> acc + x)
5

fnfold_u8fold_u8(arr, acc, f)#

Left fold over all elements (each zero-extended to Int). Argument order: collection first, init second, callback last (uncurried-collection convention). Callback f(acc, elem) = new_acc. O(n).

Examples

march> NativeArray.fold_u8(NativeArray.from_list_u8([1, 2, 3]), 0, fn (acc, x) -> acc * 10 + x)
123

fnfrom_list_f32from_list_f32(lst)#

Build a NativeF32Arr from a List(Float), rounding each element to binary32. O(n).

Examples

march> NativeArray.length_f32(NativeArray.from_list_f32([0.5, 1.5, 2.5]))
3
march> NativeArray.get_f32(NativeArray.from_list_f32([0.1]), 0) == 0.1
false

fnfrom_list_floatfrom_list_float(lst)#

Build a NativeFloatArr from a List(Float), preserving order. O(n).

Examples

march> NativeArray.length_float(NativeArray.from_list_float([0.5, 1.5]))
2

fnfrom_list_i32from_list_i32(lst)#

Build a NativeI32Arr from a List(Int), wrapping each element to i32. O(n).

Examples

march> NativeArray.to_list_i32(NativeArray.from_list_i32([-5, 2147483647]))
[-5, 2147483647]

fnfrom_list_intfrom_list_int(lst)#

Build a NativeIntArr from a List(Int), preserving order. O(n).

Examples

march> NativeArray.get_int(NativeArray.from_list_int([5, 6, 7]), 0)
5

fnfrom_list_u8from_list_u8(lst)#

Build a NativeU8Arr from a List(Int), wrapping each element mod 256. O(n).

Examples

march> NativeArray.to_list_u8(NativeArray.from_list_u8([256, -1, 300]))
[0, 255, 44]

fnget_f32get_f32(arr, i : Int)#

Return the element at index i (0-based), widened (exactly) to Float. O(1). Panics if i is negative or >= length_f32(arr).

Examples

march> NativeArray.get_f32(NativeArray.from_list_f32([0.5, 0.75]), 1)
0.75
march> NativeArray.get_f32(NativeArray.from_list_f32([16777217.0]), 0) == 16777216.0
true

fnget_floatget_float(arr, i : Int)#

Return the element at index i (0-based). O(1). Panics if i is negative or >= length_float(arr).

Examples

march> NativeArray.get_float(NativeArray.from_list_float([9.5, 8.5]), 1)
8.5

fnget_i32get_i32(arr, i : Int)#

Return the element at index i (0-based), sign-extended to Int. O(1). Panics if i is negative or >= length_i32(arr).

Examples

march> NativeArray.get_i32(NativeArray.from_list_i32([9, -8]), 1)
-8

fnget_intget_int(arr, i : Int)#

Return the element at index i (0-based). O(1). Panics if i is negative or >= length_int(arr).

Examples

march> NativeArray.get_int(NativeArray.from_list_int([10, 20, 30]), 2)
30

fnget_u8get_u8(arr, i : Int)#

Return the element at index i (0-based), zero-extended to Int (0..255). O(1). Panics if i is negative or >= length_u8(arr).

Examples

march> NativeArray.get_u8(NativeArray.from_list_u8([9, 255]), 1)
255

fni32_to_f32_arri32_to_f32_arr(arr)#

Convert a NativeI32Arr to NativeF32Arr, rounding each element to binary32 (nearest-even; exact for magnitudes up to 2^24). O(n).

Examples

march> NativeArray.to_list_f32(NativeArray.i32_to_f32_arr(NativeArray.from_list_i32([3, -4]))) == [3.0, -4.0]
true

fni32_to_int_arri32_to_int_arr(arr)#

Widen a NativeI32Arr to NativeIntArr (exact sign-extend). O(n).

Examples

march> NativeArray.to_list_int(NativeArray.i32_to_int_arr(NativeArray.from_list_i32([-7, 8])))
[-7, 8]

fnint_to_i32_arrint_to_i32_arr(arr)#

Narrow a NativeIntArr to NativeI32Arr, wrapping each element mod 2^32 two's-complement. O(n).

Examples

march> NativeArray.to_list_i32(NativeArray.int_to_i32_arr(NativeArray.from_list_int([1, -1])))
[1, -1]

fnint_to_u8_arrint_to_u8_arr(arr)#

Narrow a NativeIntArr to NativeU8Arr, wrapping each element mod 256. O(n).