std::aligned_alloc

From cppreference.com
< cpp‎ | memory‎ | c
 
 
 
Dynamic memory management
Uninitialized storage
(C++17)
(deprecated since c++17)
(deprecated since c++17)
(deprecated since c++17)
Garbage collection support
Miscellaneous
(C++11)
(C++11)
C Library
aligned_alloc
(C++17)
Low level memory management
 
Defined in header <cstdlib>
void* aligned_alloc( std::size_t alignment, std::size_t size );
(since C++17)

Allocate size bytes of uninitialized storage whose alignment is specified by alignment. The size parameter must be an integral multiple of alignment.

The following functions are required to be thread-safe:

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.

(since C++11)

Parameters

alignment - specifies the alignment. Must be a valid alignment supported by the implementation.
size - number of bytes to allocate. An integral multiple of alignment

Return value

On success, returns the pointer to the beginning of newly allocated memory. The returned pointer must be deallocated with free() or realloc().

On failure, returns a null pointer.

Notes

Passing a size which is not an integral multiple of alignment or a 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 DR 460).

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.

Regular std::malloc aligns memory suitable for any object type (which, in practice, means that it is aligned to alignof(std::max_align_t)). This function is useful for over-aligned allocations, such as to SSE, cache line, or VM page boundary.

Example

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

Possible output:

default-aligned addr:   0x2221c20
1024-byte aligned addr: 0x2222000

See also

defines the type suitable for use as uninitialized storage for types of given size
(class template)