[GHC] #14731: Document alignment & underlying size invariants for array types in GHC.Prim (was: Document alignment invariants for array types in GHC.Prim)

[GHC]

#14731: Document alignment & underlying size invariants for array types in GHC.Prim
-------------------------------------+-------------------------------------
        Reporter:  jberryman         |                Owner:  (none)
            Type:  task              |               Status:  new
        Priority:  normal            |            Milestone:
       Component:  Documentation     |              Version:  8.2.2
      Resolution:                    |             Keywords:
Operating System:  Unknown/Multiple  |         Architecture:
                                     |  Unknown/Multiple
 Type of failure:  None/Unknown      |            Test Case:
      Blocked By:                    |             Blocking:
 Related Tickets:  #2917 #9806       |  Differential Rev(s):
       Wiki Page:                    |
-------------------------------------+-------------------------------------
Description changed by jberryman:

Old description:

> Through a combination of reading some of the wiki entries on the RTS,
> some trac tickets, and experimentation I've inferred that the payloads
> for bytearray types will always be aligned to the machine word size, even
> after GC. I guess this is obvious in retrospect since otherwise non-
> pinned arrays would be pretty useless.
>
> I'm not sure what the promises are for all the `Foreign` stuff.

New description:

 Through a combination of reading some of the wiki entries on the RTS, some
 trac tickets, and experimentation I've inferred that the payloads for
 bytearray types will always be aligned to the machine word size, even
 after GC. I guess this is obvious in retrospect since otherwise non-pinned
 arrays would be pretty useless.

 Another thing I've picked up is that the memory backing a ByteArray is
 always evenly divisible by the machine word size:
 http://haskell.1045720.n5.nabble.com/Is-it-safe-to-index-a-little-bit-out-
 of-bounds-td5872779.html

 It would be great if these were documented, but more importantly (to me),
 I'd like to be able to rely on them as invariants in my own libraries. The
 first is obviously important (any code doing reads larger than single byte
 relies on it), but the second one is also really useful: e.g. I'm working
 on a hashing library that works on `text` and reads machine words for
 efficiency, doing endian adjustments as needed; it's a little easier and
 more efficient to do word-aligned word-sized "dirty" reads that cover all
 the data and then to clean up either end.

--

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/14731#comment:3>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler