[GHC] #14731: Document alignment invariants for array types in GHC.Prim

[GHC]

#14731: Document alignment 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.
>
> It can be frustrating to use `GHC.Prim` in particular due to this sort of
> lack of commitment in the docs, and these compound. Usually I end up
> trying to find an example in `text` or `bytestring` that would be
> horribly broken if some undocumented behavior changed, and hang my hat on
> that with a sad comment in the code I'm writing.

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.

 I'm not sure what the promises are for all the `Foreign` stuff.

--

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