1[/
2  Copyright 2007 John Maddock.
3  Distributed under the Boost Software License, Version 1.0.
4  (See accompanying file LICENSE_1_0.txt or copy at
5  http://www.boost.org/LICENSE_1_0.txt).
6]
7
8[section:aligned_storage aligned_storage]
9
10   template <std::size_t Size, std::size_t Align>
11   struct aligned_storage
12   {
13      typedef __below type;
14   };
15
16__type a built-in or POD type with size `Size` and an alignment
17that is a multiple of `Align`.
18
19__header ` #include <boost/type_traits/aligned_storage.hpp>` or ` #include <boost/type_traits.hpp>`
20
21On the GCC and Visual C++ compilers (or compilers that are compatible with them), we support
22requests for types with alignments greater than any built in type (up to 128-bit alignment).
23Visual C++ users should note that such "extended" types can not be passed down the stack as
24by-value function arguments.
25
26[important
27Visual C++ users should be aware that MSVC has an elastic definition of alignment, for
28example consider the following code:
29
30``
31   typedef boost::aligned_storage<8,8>::type align_t;
32   assert(boost::alignment_of<align_t>::value % 8 == 0);
33   align_t a;
34   assert(((std::uintptr_t)&a % 8) == 0);
35   char c = 0;
36   align_t a1;
37   assert(((std::uintptr_t)&a1 % 8) == 0);
38``
39
40In this code the final assert will fail for a 32-bit build because variable `a1` is not
41aligned on an 8-byte boundary.  Had we used the MSVC intrinsic `__alignof` in
42place of `alignment_of` or `std::aligned_storage` in place of `boost::aligned_storage`
43the result would have been no different.  In MSVC alignment requirements/promises only
44really apply to variables on the heap, not on the stack.
45
46Further, although MSVC has a mechanism for generating new types with arbitrary alignment
47requirements, such types cannot be passed as function arguments on the program stack.
48Therefore had `boost::aligned_storage<8,8>::type` been a type declared with
49`__declspec(align(8))` we would break a great deal of existing code that relies on
50being able to pass such types through the program stack.
51]
52
53[endsect]
54
55