#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

#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

#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: | -------------------------------------+------------------------------------- Comment (by jberryman): Documenting `newAlignedPinnedByteArray#` is also relevant. It seems that the alignment argument is only important for data that needs to be aligned to greater than word size (i.e. all byte arrays, pinned or not are word aligned). It's awkward to future-proof code for the case where GHC starts storing pinned arrays more tightly aligned. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14731#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler