PaUtil_AllocateMemory doc omits value for alignment guarantees

[PortAudio-admin]

Issue created by @RossBencina

The current documentation for PaUtil_AllocateMemory reads:

Allocate size bytes, guaranteed to be aligned to a FIXME byte boundary <<

We should decide whether we want to make alignment guarantees. Recent discussions re the ringbufer imply that we should at least make some minimal guarantee (such as alignment to sizeof(int)).

It might be better to introduce PaUtil_AllocateAlignedMemory( size, alignment ) for larger alignments.

Also: Document and adhere to the alignment guarantees provided by PaUtil_AllocateMemory().

see: http://www.portaudio.com/docs/v19-doxydocs/pa__util_8h.html

[PortAudio-admin]

Comment by @RossBencina

TRAC migration: propagating ticket status from TRAC

[RossBencina]

On Windows, PortAudio uses GlobalAlloc, which has an 8-byte alignment guarantee:

Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary. -- https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-globalalloc

On other platforms (specifically, when pa_unix_util.c is used) PortAudio uses malloc, which typically has an 8 or 16 byte alignment guarantee. That said, the C89 standard states (sec7.10.3, paragraph 1):

The pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a pointer to any type of object and then used to access such an object, or an array of such objects in the space allocated.

Note that this wording does not require that the alignment is at least 8 (i.e. sizeof(double)) if the platform supports unaligned access. Thus the guarantee is dependent on the platform. Also it is not explicit that the alignment is guaranteed to support platform-specific types such as SIMD vector types -- although this is implied by the wording "any type".

Note that there seems to be some controversy as to whether malloc must return 16-byte-aligned memory for an 8 byte allocation, see: https://github.com/jemalloc/jemalloc/issues/1533allocation

[RossBencina]

Phil and I think that any kind of custom aligned allocator impl would be a separate API. To resolve this ticket we simply need to document the alignment that is guaranteed by PaUtil_AllocateMemory / (now called PaUtil_AllocateZeroInitializedMemory. This could be as simple as:

"On Unix, the memory has the same alignment as memory returned by malloc(). On Windows the alignment is that of GlobalAlloc that is 8-bytes."