[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:
b380ddad by Ben Gamari at 2024-10-09T10:59:02-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 ::
+
+    data T = T {-# UNPACK #-} !Word32 {-# UNPACK #-} !Word32
+
+As ``Word16`` is represented by the unlifted 32-bit ``Word32#`` type, the ``T``
+constructor will be 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 32-bit platform ::
+
+    data T = T {-# UNPACK #-} !Word16
+               {-# UNPACK #-} !Word8
+               {-# UNPACK #-} !Word16
+
+will require two words since padding is necessary after the ``Word8`` to
+ensure that the subsequent ``Word32`` is naturally aligned:
+
+.. code-block:: none
+
+     ┌───────────────────────────────────┐
+     │ Header                            │
+     ├─────────────────┬────────┬────────┤
+     │ Word16          │ Word8  │ padding│
+     ├─────────────────┴────────┴────────┤
+     │ Word16                            │
+     └───────────────────────────────────┘
+
 .. [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/b380ddadb5e5376326e4128634cbfd72ab51e0dd

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/b380ddadb5e5376326e4128634cbfd72ab51e0dd
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/20241009/0fc6a4eb/attachment-0001.html>