diff --git a/doc/aligned_storage.qbk b/doc/aligned_storage.qbk index 582e39a..92ecca1 100644 --- a/doc/aligned_storage.qbk +++ b/doc/aligned_storage.qbk @@ -18,5 +18,37 @@ that is a multiple of `Align`. __header ` #include ` or ` #include ` +On the GCC and Visual C++ compilers (or compilers that are compatible with them), we support +requests for types with alignments greater than any built in type (up to 128-bit alignment). +Visual C++ users should note that such "extended" types can not be passed down the stack as +by-value function arguments. + +[important +Visual C++ users should be aware that MSVC has an elastic definition of alignment, for +example consider the following code: + +`` + typedef boost::aligned_storage<8,8>::type align_t; + assert(boost::alignment_of::value % 8 == 0); + align_t a; + assert(((std::uintptr_t)&a % 8) == 0); + char c = 0; + align_t a1; + assert(((std::uintptr_t)&a1 % 8) == 0); +`` + +In this code the final assert will fail for a 32-bit build because variable `a1` is not +aligned on an 8-byte boundary. Had we used the MSVC intrinsic `__alignof` in +place of `alignment_of` or `std::aligned_storage` in place of `boost::aligned_storage` +the result would have been no different. In MSVC alignment requirements/promises only +really apply to variables on the heap, not on the stack. + +Further, although MSVC has a mechanism for generating new types with arbitrary alignment +requirements, such types cannot be passed as function arguments on the program stack. +Therefore had `boost::aligned_storage<8,8>::type` been a type declared with +`__declspec(align(8))` we would break a great deal of existing code that relies on +being able to pass such types through the program stack. +] + [endsect] diff --git a/doc/alignment_of.qbk b/doc/alignment_of.qbk index 97c6bf3..0b9f0b5 100644 --- a/doc/alignment_of.qbk +++ b/doc/alignment_of.qbk @@ -30,5 +30,26 @@ expression with value `ALIGNOF(double)`.] [:`alignment_of::value_type` is the type `std::size_t`.] +[important +Visual C++ users should note that MSVC has varying definitions of "alignment". +For example consider the following code: + +`` + typedef long long align_t; + assert(boost::alignment_of::value % 8 == 0); + align_t a; + assert(((std::uintptr_t)&a % 8) == 0); + char c = 0; + align_t a1; + assert(((std::uintptr_t)&a1 % 8) == 0); +`` + +In this code, even though `boost::alignment_of` reports that `align_t` has 8-byte +alignment, the final assert will fail for a 32-bit build because `a1` is not aligned on an +8 byte boundary. Note that had we used the MSVC intrinsic `__alignof` in place of `boost::alignment_of` +we would still get the same result. In fact for MSVC alignment requirements (and promises) only really +apply to dynamic storage, and not the stack. +] + [endsect] diff --git a/doc/html/boost_typetraits/reference/aligned_storage.html b/doc/html/boost_typetraits/reference/aligned_storage.html index c11176a..4189362 100644 --- a/doc/html/boost_typetraits/reference/aligned_storage.html +++ b/doc/html/boost_typetraits/reference/aligned_storage.html @@ -42,6 +42,54 @@ <boost/type_traits/aligned_storage.hpp> or #include <boost/type_traits.hpp>

+

+ On the GCC and Visual C++ compilers (or compilers that are compatible with + them), we support requests for types with alignments greater than any built + in type (up to 128-bit alignment). Visual C++ users should note that such + "extended" types can not be passed down the stack as by-value function + arguments. +

+
+ + + + + +
[Important]Important
+

+ Visual C++ users should be aware that MSVC has an elastic definition of + alignment, for example consider the following code: +

+

+

+
typedef boost::aligned_storage<8,8>::type align_t;
+assert(boost::alignment_of<align_t>::value % 8 == 0);
+align_t a;
+assert(((std::uintptr_t)&a % 8) == 0);
+char c = 0;
+align_t a1;
+assert(((std::uintptr_t)&a1 % 8) == 0);
+
+

+

+

+ In this code the final assert will fail for a 32-bit build because variable + a1 is not aligned on an + 8-byte boundary. Had we used the MSVC intrinsic __alignof + in place of alignment_of + or std::aligned_storage in place of boost::aligned_storage the result would have + been no different. In MSVC alignment requirements/promises only really + apply to variables on the heap, not on the stack. +

+

+ Further, although MSVC has a mechanism for generating new types with arbitrary + alignment requirements, such types cannot be passed as function arguments + on the program stack. Therefore had boost::aligned_storage<8,8>::type + been a type declared with __declspec(align(8)) + we would break a great deal of existing code that relies on being able + to pass such types through the program stack. +

+
diff --git a/doc/html/boost_typetraits/reference/alignment_of.html b/doc/html/boost_typetraits/reference/alignment_of.html index 4d9e67a..8bd65cc 100644 --- a/doc/html/boost_typetraits/reference/alignment_of.html +++ b/doc/html/boost_typetraits/reference/alignment_of.html @@ -62,6 +62,38 @@

alignment_of<T>::value_type is the type std::size_t.

+
+ + + + + +
[Important]Important
+

+ Visual C++ users should note that MSVC has varying definitions of "alignment". + For example consider the following code: +

+

+

+
typedef long long align_t;
+assert(boost::alignment_of<align_t>::value % 8 == 0);
+align_t a;
+assert(((std::uintptr_t)&a % 8) == 0);
+char c = 0;
+align_t a1;
+assert(((std::uintptr_t)&a1 % 8) == 0);
+
+

+

+

+ In this code, even though boost::alignment_of<align_t> reports that align_t + has 8-byte alignment, the final assert will fail for a 32-bit build because + a1 is not aligned on an + 8 byte boundary. Note that had we used the MSVC intrinsic __alignof in place of boost::alignment_of + we would still get the same result. In fact for MSVC alignment requirements + (and promises) only really apply to dynamic storage, and not the stack. +

+
diff --git a/doc/html/index/s11.html b/doc/html/index/s11.html index 1f9c4cc..e47e64f 100644 --- a/doc/html/index/s11.html +++ b/doc/html/index/s11.html @@ -24,7 +24,7 @@

-Class Index

+Class Index

A C D E F H I M N O P R T

diff --git a/doc/html/index/s12.html b/doc/html/index/s12.html index 64486a6..fb12151 100644 --- a/doc/html/index/s12.html +++ b/doc/html/index/s12.html @@ -24,10 +24,20 @@

-Typedef Index

-

F R T

+Typedef Index
+

A F R T

+A +
+
+
F
  • diff --git a/doc/html/index/s13.html b/doc/html/index/s13.html index bbb245f..e9810d3 100644 --- a/doc/html/index/s13.html +++ b/doc/html/index/s13.html @@ -24,7 +24,7 @@

-Macro Index

+Macro Index

B

diff --git a/doc/html/index/s14.html b/doc/html/index/s14.html index 05626dc..3387266 100644 --- a/doc/html/index/s14.html +++ b/doc/html/index/s14.html @@ -23,7 +23,7 @@

-Index

+Index

A B C D E F H I M N O P R T U

@@ -37,15 +37,29 @@

  • add_reference

  • add_rvalue_reference

  • add_volatile

    • -

  • aligned_storage

    • +
  • +

    aligned_storage

    +
    +

  • alignment_of

  • +

    align_t

    +
    +
    • +

  • any