std:: aligned_alloc

Allocate size bytes of uninitialized storage whose alignment is specified by alignment ( implicitly creating objects in the destination area). The size parameter must be an integral multiple of alignment .

The following functions are required to be thread-safe:

• The library versions of operator new and operator delete
• User replacement versions of global operator new and operator delete
• std::calloc , std::malloc , std::realloc , std::aligned_alloc , std::free

Calls to these functions that allocate or deallocate a particular unit of storage occur in a single total order, and each such deallocation call happens-before the next allocation (if any) in this order.

Parameters

Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with std::free or std::realloc .

On failure, returns a null pointer.

Notes

Passing a size which is not an integral multiple of alignment or an alignment which is not valid or not supported by the implementation causes the function to fail and return a null pointer (C11, as published, specified undefined behavior in this case, this was corrected by DR460 ).

As an example of the "supported by the implementation" requirement, POSIX function posix_memalign accepts any alignment that is a power of two and a multiple of sizeof ( void * ) , and POSIX-based implementations of aligned_alloc inherit this requirements.

Fundamental alignments are always supported. If alignment is a power of two and not greater than alignof ( std:: max_align_t ) , aligned_alloc may simply call std::malloc .

Regular std::malloc aligns memory suitable for any object type with a fundamental alignment. This function is useful for over-aligned allocations, such as to SSE , cache line, or VM page boundary.

This function is not supported in Microsoft C Runtime library because its implementation of std::free is unable to handle aligned allocations of any kind. Instead, MS CRT provides _aligned_malloc (to be freed with _aligned_free ).

Example

#include <cstdio>
#include <cstdlib>
 
int main()
{
    int* p1 = static_cast<int*>(std::malloc(10 * sizeof *p1));
    std::printf("default-aligned address:   %p\n", static_cast<void*>(p1));
    std::free(p1);
 
    int* p2 = static_cast<int*>(std::aligned_alloc(1024, 1024));
    std::printf("1024-byte aligned address: %p\n", static_cast<void*>(p2));
    std::free(p2);
}

default-aligned address:   0x2221c20
1024-byte aligned address: 0x2222400

See also