Namespaces
Variants
Views
Actions

std::aligned_alloc

From cppreference.com
< cpp‎ | memory‎ | c
 
 
Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (C++20)
Dynamic memory management
Program utilities
Coroutine support (C++20)
Variadic functions
Debugging support
(C++26)
Three-way comparison
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)

 
Dynamic memory management
Uninitialized memory algorithms
Constrained uninitialized memory algorithms
Allocators
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)



 
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 (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:

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.

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 std::free or std::realloc.

On failure, returns a null pointer.

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

[edit] 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);
}

Possible output:

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

[edit] See also

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