[Git][ghc/ghc][wip/raehik/primop-array-mutability-docs] Note mutability of array and address access primops

[Ben Orchard (@raehik)]

Ben Orchard pushed to branch wip/raehik/primop-array-mutability-docs at Glasgow Haskell Compiler / GHC


Commits:
f4d3406d by Ben Orchard at 2024-03-13T14:31:08+00:00
Note mutability of array and address access primops

Without an understanding of immutable vs. mutable memory, the index
primop family have a potentially non-intuitive type signature:

    indexOffAddr :: Addr# -> Int# -> a
    readOffAddr  :: Addr# -> Int# -> State# d -> (# State# d, a #)

indexOffAddr# might seem like a free generality improvement, which it
certainly is not!

This change adds a brief note on mutability expectations for most
index/read/write access primops.

- - - - -


1 changed file:

- utils/genprimopcode/AccessOps.hs


Changes:

=====================================
utils/genprimopcode/AccessOps.hs
=====================================
@@ -82,7 +82,7 @@ mkIndexByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
              (elt_rep_ty e)
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ "."
+  , desc = "Read " ++ elt_desc e ++ " from immutable array; offset in " ++ prettyOffset e ++ "."
   , opts = [OptionEffect CanFail]
   }
 
@@ -94,7 +94,7 @@ mkUnalignedIndexByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
              (elt_rep_ty e)
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Read " ++ elt_desc e ++ " from immutable array; offset in bytes."
   , opts = [OptionEffect CanFail]
   }
 
@@ -106,7 +106,7 @@ mkReadByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ readResTy e
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ "."
+  , desc = "Read " ++ elt_desc e ++ " from mutable array; offset in " ++ prettyOffset e ++ "."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 
@@ -118,7 +118,7 @@ mkUnalignedReadByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ readResTy e
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Read " ++ elt_desc e ++ " from mutable array; offset in bytes."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 
@@ -130,7 +130,7 @@ mkWriteByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ writeResTy e
   , cat = GenPrimOp
-  , desc = "Write " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ "."
+  , desc = "Write " ++ elt_desc e ++ " to mutable array; offset in " ++ prettyOffset e ++ "."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 
@@ -142,7 +142,7 @@ mkUnalignedWriteByteArrayOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ writeResTy e
   , cat = GenPrimOp
-  , desc = "Write " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Write " ++ elt_desc e ++ " to mutable array; offset in bytes."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 
@@ -166,7 +166,7 @@ mkIndexOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
              (elt_rep_ty e)
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ ".\n\n"
+  , desc = "Read " ++ elt_desc e ++ " from immutable address; offset in " ++ prettyOffset e ++ ".\n\n"
            ++ getAlignWarn e
   , opts = [OptionEffect CanFail]
   }
@@ -179,7 +179,7 @@ mkUnalignedIndexOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
              (elt_rep_ty e)
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Read " ++ elt_desc e ++ " from immutable address; offset in bytes."
   , opts = [OptionEffect CanFail]
   }
 
@@ -191,7 +191,7 @@ mkReadOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ readResTy e
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ ".\n\n"
+  , desc = "Read " ++ elt_desc e ++ " from mutable address; offset in " ++ prettyOffset e ++ ".\n\n"
            ++ getAlignWarn e
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
@@ -204,7 +204,7 @@ mkUnalignedReadOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ readResTy e
   , cat = GenPrimOp
-  , desc = "Read " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Read " ++ elt_desc e ++ " from mutable address; offset in bytes."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 
@@ -216,7 +216,7 @@ mkWriteOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ writeResTy e
   , cat = GenPrimOp
-  , desc = "Write " ++ elt_desc e ++ "; offset in " ++ prettyOffset e ++ ".\n\n"
+  , desc = "Write " ++ elt_desc e ++ " to mutable address; offset in " ++ prettyOffset e ++ ".\n\n"
            ++ getAlignWarn e
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
@@ -229,7 +229,7 @@ mkUnalignedWriteOffAddrOp e = PrimOpSpec
        $ TyF (strToTy "Int#")
        $ writeResTy e
   , cat = GenPrimOp
-  , desc = "Write " ++ elt_desc e ++ "; offset in bytes."
+  , desc = "Write " ++ elt_desc e ++ " to mutable address; offset in bytes."
   , opts = [OptionEffect ReadWriteEffect, OptionCanFailWarnFlag YesWarnCanFail]
   }
 



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/f4d3406d13abb4a32020d303181982be7800f5ff

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/f4d3406d13abb4a32020d303181982be7800f5ff
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240313/4e0600cf/attachment-0001.html>