mallocForeignPtrBytes documentation unobvious regarding memory alignment

According to the current documentation:

mallocForeignPtr - is equivalent to do { p <- malloc; newForeignPtr finalizerFree p }. It's ok since we can read that the "block of memory is sufficiently aligned" if the mallocBytes function descriprion and newAlignedPinnedByteArray in the function implementation.

mallocForeignPtrBytes - "similar to mallocForeignPtr" but will it alloc aligned memory? Internally it uses newPinnedByteArray which implies memory will not be aligned, but does it really makes any sense?

Plz correct documentation to make it more obvious.

Trac metadata

Trac field	Value
Version	7.6.3
Type	Bug
TypeOfFailure	OtherFailure
Priority	normal
Resolution	Unresolved
Component	Documentation
Test case
Differential revisions
BlockedBy
Related
Blocking
CC
Operating system
Architecture

changed weight to 5

added Tbug Trac import documentation labels

assigned to @trac-ekmett

Trac metadata

Trac field	Value
TypeOfFailure	OtherFailure → DocumentationBug
Component	Documentation → Core Libraries
CC	→ core-libraries-committee@haskell.org

added core libraries label

mallocForeignPtrBytes provides no alignment guarantees. You should in theory need to pad your request by (alignment - 1) bytes and align the resulting memory by hand.

We're missing a mallocForeignPtrBytesAligned, which would behave like allocaBytesAligned which probably should become a separate issue.

mentioned in issue #9806

Trac metadata

Trac field	Value
Related	→ #9806

Leaving this ticket open to address the documentation issue.

I've opened #9806 to address potential library changes though.

added Pnormal label