Namespaces
Variants
Views
Actions

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++20)
(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)

Contents

[edit] 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

[edit] 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 free() or realloc().

On failure, returns a null pointer.

[edit] 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.

[edit] 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

[edit] See also

defines the type suitable for use as uninitialized storage for types of given size
(class template) [edit]
C documentation for aligned_alloc