home | help 
std::aligned_alloc(3)	       C++ Standard Libary	   std::aligned_alloc(3)

NAME
     std::aligned_alloc - std::aligned_alloc

Synopsis
	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  speci-
     fied 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
	alignment - specifies the alignment. Must be a valid alignment supported
     by the
		    implementation.
	size	   - number of bytes to allocate. An integral multiple of align-
     ment.

Return value
	On success, returns the pointer to the beginning of newly allocated mem-
     ory. 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 multi-
     ple 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
     // Run this code

      #include <cstdio>
      #include <cstdlib>

      int main()
      {
	  int* p1 = static_cast<int*>(std::malloc(10 * sizeof *p1));
	  std::printf("default-aligned	     address:	      %p\n",	    sta-
     tic_cast<void*>(p1));
	  std::free(p1);

	  int* p2 = static_cast<int*>(std::aligned_alloc(1024, 1024));
	  std::printf("1024-byte      aligned	   address:	 %p\n",     sta-
     tic_cast<void*>(p2));
	  std::free(p2);
      }

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

See also
	aligned_storage 	     defines the type suitable for use as unini-
     tialized
	(C++11)(deprecated in C++23) storage for types of given size
				     (class template)
	C documentation for
	aligned_alloc

http://cppreference.com 	   2024.06.10		   std::aligned_alloc(3)
home | help