[Git][ghc/ghc][wip/doc-unpack] users-guide: Document field coalescence

[Ben Gamari (@bgamari)]

Ben Gamari pushed to branch wip/doc-unpack at Glasgow Haskell Compiler / GHC


Commits:
3481b865 by Ben Gamari at 2024-10-13T20:33:55-04:00
users-guide: Document field coalescence

- - - - -


1 changed file:

- docs/users_guide/exts/pragmas.rst


Changes:

=====================================
docs/users_guide/exts/pragmas.rst
=====================================
@@ -959,6 +959,35 @@ effect of adding ``{-# UNPACK #-}`` to every strict constructor field which is
 of a single-constructor data type. Sum types won't be unpacked automatically
 by this though, only with the explicit pragma.
 
+Also note that GHC will coalesce adjacent sub-word size fields into
+words. For instance, consider (on a 64-bit platform) ::
+
+    data T = T {-# UNPACK #-} !Word32 {-# UNPACK #-} !Word32
+
+As ``Word32`` is represented by the unlifted 32-bit ``Word32#`` type, the ``T``
+constructor will represent its two ``Word32`` fields using only a single
+64-bit word.
+
+Note that during coalescence padding will be inserted to ensure that each field
+remains naturally aligned. For instance, on a 64-bit platform ::
+
+    data T = T {-# UNPACK #-} !Word32
+               {-# UNPACK #-} !Word8
+               {-# UNPACK #-} !Word32
+
+the fields of ``T`` require two 64-bit words since padding is necessary after
+the ``Word8`` to ensure that the subsequent ``Word64`` is naturally aligned:
+
+.. code-block:: none
+
+     ┌───────────────────────────────────┐
+     │ Header                            │
+     ├─────────────────┬────────┬────────┤
+     │ Word32          │ Word8  │ padding│
+     ├─────────────────┼────────┴────────┤
+     │ Word32          │ padding         │
+     └─────────────────┴─────────────────┘
+
 .. [1]
    In fact, :pragma:`UNPACK` has no effect without :ghc-flag:`-O`, for technical
    reasons (see :ghc-ticket:`5252`).



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

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/3481b86501026d1e5f88213675ff8e5d47ad4874
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/20241013/90b2836b/attachment-0001.html>