Make Indexing return ordering tokens

Author: Jaro Reinders

README.md

@@ -2,15 +2,33 @@
 
 Situation:
 
-* All references to an immutable data structure have the same value
-* Using immutable data structures makes it easier to reason about your programs
-* Mutation can always be avoided by creating a modified copy instead.
-
-Complication:
+* There is one essential idea that I must explain properly. Usually in Haskell
+  you think of everything as a value. However, under the hood most things are
+  implemented using references. Everytime I say "old version" or "old
+  reference", I refer to this implementation detail. There is no way to really
+  explain it without explaining how references are used in the implementation of
+  Haskell.
 
-* Unfortunately, such copying has a high performance cost.
-* In particular, if you only modify a small part of a large data structure, then the whole structure must be copied
-* This can turn constant-time operations into linear-time operations.
+* Using immutable data structures makes it easier to reason about your programs
+  (motivation)
+* All references to an immutable data structure have the same value
+  (restriction)
+* Mutation can always be avoided by creating a modified copy instead (bad
+  previous solution).
+* Copying can be cheap, if the data that needs to be copied is not much larger
+  than the data that has been changed
+* That happens, for example, when changing the first element of a linked list.
+  The remainder of the list can be shared in memory.
+
+Complication (why is it bad?):
+
+* Arrays, on the other hand, are an example of a data structure where changes
+  can be much smaller than the copied data.
+* In an array, changing a single element would necessitate a copy of the entire
+  array.
+* Thus, such copying unfortunately has a high performance cost.
+* Copying can turn constant-time operations into linear-time operations (and
+  linear-time into quadratic-time, etc.).
 
 Question:
 
@@ -19,4 +37,6 @@ Question:
 Answer:
 
 * Do the mutation, but keep track of changes
-* Whenever the old version is used after the mutation, reapply the changes
+* Old references to the same data will be mutated in an equal but opposite way
+* Whenever the old version is used after the mutation, reapply the changes
+

examples/Example/Fleet/Quicksort.hs

@@ -2,15 +2,14 @@
 module Example.Fleet.Quicksort (quicksort) where
 
 import Fleet.Array
-import Data.Tuple (Solo (MkSolo))
 
 {-# INLINEABLE quicksort #-}
 quicksort :: Ord a => Int -> Int -> Array a -> Array a
 quicksort !l !r !xs
   | r - l <= 1 = xs
   | otherwise =
-    let x@(MkSolo x') = index (r - 1) xs in
-    x `pseq` case partition l (r - 1) xs x' of
+    let (x', t) = index (r - 1) xs in
+    case partition l (r - 1) (tag t xs) x' of
       (xs, m) -> quicksort l m (quicksort (m + 1) r (swap (r - 1) m xs))
 
 {-# INLINEABLE partition #-}

src/Fleet/Array.hs

@@ -28,6 +28,7 @@ module Fleet.Array
   , toList
   , (!)
   , index
+  , tag
   , set
   , copy
   , swap
@@ -36,7 +37,6 @@ module Fleet.Array
 
 import Prelude hiding (replicate)
 
-import Data.Tuple (Solo (MkSolo))
 import GHC.Exts hiding (fromList, toList, Lifted)
 
 import Data.Kind (Type)
@@ -157,25 +157,55 @@ A v0 ! i0 = unsafeDupablePerformIO (go v0 i0) where
         | i == j2 -> go v' j1
         | otherwise -> go v' i
 
+data Token = Token (State# RealWorld)
+
+returnToken :: a -> IO (a, Token)
+returnToken x = IO (\s -> (# s , (x, Token s) #))
+
 -- | Indexing an array. O(1)
--- Using the 'Solo' constructor, you can sequence indexing to happen before
--- future updates without having to evaluate the element itself.
+--
+-- The tuple and 'Token' serve two purposes:
+--
+-- - You can now separately force the evaluation of the tuple and the actual
+--   array element
+-- - You can use the 'Token' to with the 'tag' function on an array to force
+--   the indexing to happen before the array can be written to.
 {-# INLINE index #-}
-index :: Int -> Array a -> Solo a
+index :: Int -> Array a -> (a, Token)
 index i0 (A v0) = unsafeDupablePerformIO (go v0 i0) where
   go v i = do
     dat <- readMutVar v
     case dat of
-      Current arr -> MkSolo <$> readMutArray arr i
+      Current arr -> readMutArray arr i >>= returnToken
       -- _ -> error "Accessing old version"
       Diff (Set j x) xs
-        | i == j -> pure (MkSolo x)
+        | i == j -> returnToken x
         | otherwise -> go xs i
       Diff (Swap j1 j2) xs
         | i == j1 -> go xs j2
         | i == j2 -> go xs j1
         | otherwise -> go xs i
 
+-- | This is a no-op, but can be used to enforce an ordering between indexing
+-- and other array operations, to avoid the overhead of indexing from older
+-- versions of the array.
+--
+-- For example, swapping two elements in an array by using 'index'
+-- and 'set' can be done like this:
+--
+-- @
+-- swap :: Int -> Int -> Array a -> Array a
+-- swap i j xs =
+--   let (x, t1) = index i xs
+--       (y, t2) = index j xs
+--   in set i y (set j x (tag t1 (tag t2 xs)))
+-- @
+--
+-- This ensures the indexing happens before the setting.
+{-# NOINLINE tag #-}
+tag :: Token -> Array a -> Array a
+tag (Token _) xs = xs
+
 {-# INLINE invert #-}
 invert :: MutArray a -> Op a -> IO (Op a)
 invert _ (Swap i j) = pure (Swap i j)