From e9a0873ceb5c2140dc3331aa8239d511675d55c4 Mon Sep 17 00:00:00 2001 From: Tom Smeding Date: Sat, 15 Nov 2025 22:48:06 +0100 Subject: README: Document array buffer sharing policy --- README.md | 8 ++++++++ src/Data/Array/XArray.hs | 1 - 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 01bcbac..2e24c91 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,14 @@ as precisely as you want to GHC what exactly you're doing. Below the surface layer, there is a more low-level wrapper (`XArray`) around `orthotope` that defines a non-nested `Mixed`-style array type. +**Be aware**: `ox-arrays` attempts to preserve sharing as much as possible. +That is to say: if a function is able avoid copying array data and return an +array that references the original underlying `Vector`, it may do so. For +example, this means that if you convert a nested array to a list of arrays, all +returned arrays reference part of the original array without copying. This +makes `mtoList` fast, but also means that memory may be retained longer than +you might expect. + Here is a little taster of the API, to get a sense for the design: ```haskell diff --git a/src/Data/Array/XArray.hs b/src/Data/Array/XArray.hs index 6ad48cc..29154f1 100644 --- a/src/Data/Array/XArray.hs +++ b/src/Data/Array/XArray.hs @@ -308,7 +308,6 @@ toListOuter (XArray arr@(ORS.A (ORG.A _ t))) = 0 : _ -> [] -- using orthotope's functions here would entail using rerank, which is slow, so we don't [_] | Refl <- (unsafeCoerceRefl :: sh :~: '[]) -> coerce (map S.scalar $ S.toList arr) - -- TODO: this shares the backing array among all the results; is that what we want? n : sh -> coerce $ map (ORG.A sh . OI.indexT t) [0 .. n - 1] fromList1 :: Storable a => StaticShX '[n] -> [a] -> XArray '[n] a -- cgit v1.2.3-70-g09d2