mirror of
https://github.com/boostorg/type_traits.git
synced 2025-07-29 20:17:21 +02:00
Update docs on alignment traits.
This commit is contained in:
jzmaddock
@ -18,5 +18,37 @@ that is a multiple of `Align`.
|
||||
|
||||
__header ` #include <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
|
||||
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.
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -30,5 +30,26 @@ expression with value `ALIGNOF(double)`.]
|
||||
|
||||
[:`alignment_of<T>::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<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.
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -42,6 +42,54 @@
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">aligned_storage</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
or <code class="computeroutput"> <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">type_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<div class="important"><table border="0" summary="Important">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
|
||||
<th align="left">Important</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
Visual C++ users should be aware that MSVC has an elastic definition of
|
||||
alignment, for example consider the following code:
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">aligned_storage</span><span class="special"><</span><span class="number">8</span><span class="special">,</span><span class="number">8</span><span class="special">>::</span><span class="identifier">type</span> <span class="identifier">align_t</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">alignment_of</span><span class="special"><</span><span class="identifier">align_t</span><span class="special">>::</span><span class="identifier">value</span> <span class="special">%</span> <span class="number">8</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="identifier">align_t</span> <span class="identifier">a</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uintptr_t</span><span class="special">)&</span><span class="identifier">a</span> <span class="special">%</span> <span class="number">8</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="keyword">char</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">align_t</span> <span class="identifier">a1</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uintptr_t</span><span class="special">)&</span><span class="identifier">a1</span> <span class="special">%</span> <span class="number">8</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
In this code the final assert will fail for a 32-bit build because variable
|
||||
<code class="computeroutput"><span class="identifier">a1</span></code> is not aligned on an
|
||||
8-byte boundary. Had we used the MSVC intrinsic <code class="computeroutput"><span class="identifier">__alignof</span></code>
|
||||
in place of <code class="computeroutput"><span class="identifier">alignment_of</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">aligned_storage</span></code> in place of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">aligned_storage</span></code> the result would have
|
||||
been no different. In MSVC alignment requirements/promises only really
|
||||
apply to variables on the heap, not on the stack.
|
||||
</p>
|
||||
<p>
|
||||
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 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">aligned_storage</span><span class="special"><</span><span class="number">8</span><span class="special">,</span><span class="number">8</span><span class="special">>::</span><span class="identifier">type</span></code>
|
||||
been a type declared with <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">align</span><span class="special">(</span><span class="number">8</span><span class="special">))</span></code>
|
||||
we would break a great deal of existing code that relies on being able
|
||||
to pass such types through the program stack.
|
||||
</p>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
|
||||
@ -62,6 +62,38 @@
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<code class="computeroutput"><span class="identifier">alignment_of</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">value_type</span></code> is the type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
|
||||
</p></blockquote></div>
|
||||
<div class="important"><table border="0" summary="Important">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
|
||||
<th align="left">Important</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
Visual C++ users should note that MSVC has varying definitions of "alignment".
|
||||
For example consider the following code:
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">align_t</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">alignment_of</span><span class="special"><</span><span class="identifier">align_t</span><span class="special">>::</span><span class="identifier">value</span> <span class="special">%</span> <span class="number">8</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="identifier">align_t</span> <span class="identifier">a</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uintptr_t</span><span class="special">)&</span><span class="identifier">a</span> <span class="special">%</span> <span class="number">8</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="keyword">char</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">align_t</span> <span class="identifier">a1</span><span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uintptr_t</span><span class="special">)&</span><span class="identifier">a1</span> <span class="special">%</span> <span class="number">8</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
In this code, even though <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">alignment_of</span><span class="special"><</span><span class="identifier">align_t</span><span class="special">></span></code> reports that <code class="computeroutput"><span class="identifier">align_t</span></code>
|
||||
has 8-byte alignment, the final assert will fail for a 32-bit build because
|
||||
<code class="computeroutput"><span class="identifier">a1</span></code> is not aligned on an
|
||||
8 byte boundary. Note that had we used the MSVC intrinsic <code class="computeroutput"><span class="identifier">__alignof</span></code> in place of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">alignment_of</span></code>
|
||||
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.
|
||||
</p>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
|
||||
@ -24,7 +24,7 @@
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="idm1547040384"></a>Class Index</h2></div></div></div>
|
||||
<a name="idm1548324560"></a>Class Index</h2></div></div></div>
|
||||
<p><a class="link" href="s11.html#idx_id_0">A</a> <a class="link" href="s11.html#idx_id_2">C</a> <a class="link" href="s11.html#idx_id_3">D</a> <a class="link" href="s11.html#idx_id_4">E</a> <a class="link" href="s11.html#idx_id_5">F</a> <a class="link" href="s11.html#idx_id_6">H</a> <a class="link" href="s11.html#idx_id_7">I</a> <a class="link" href="s11.html#idx_id_8">M</a> <a class="link" href="s11.html#idx_id_9">N</a> <a class="link" href="s11.html#idx_id_10">O</a> <a class="link" href="s11.html#idx_id_11">P</a> <a class="link" href="s11.html#idx_id_12">R</a> <a class="link" href="s11.html#idx_id_13">T</a></p>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt>
|
||||
|
||||
@ -24,10 +24,20 @@
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="idm1546660224"></a>Typedef Index</h2></div></div></div>
|
||||
<p><a class="link" href="s12.html#idx_id_20">F</a> <a class="link" href="s12.html#idx_id_27">R</a> <a class="link" href="s12.html#idx_id_28">T</a></p>
|
||||
<a name="idm1547944400"></a>Typedef Index</h2></div></div></div>
|
||||
<p><a class="link" href="s12.html#idx_id_15">A</a> <a class="link" href="s12.html#idx_id_20">F</a> <a class="link" href="s12.html#idx_id_27">R</a> <a class="link" href="s12.html#idx_id_28">T</a></p>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt>
|
||||
<a name="idx_id_15"></a><span class="term">A</span>
|
||||
</dt>
|
||||
<dd><div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none">
|
||||
<p><span class="index-entry-level-0">align_t</span></p>
|
||||
<div class="index"><ul class="index" style="list-style-type: none; ">
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/aligned_storage.html" title="aligned_storage"><span class="index-entry-level-1">aligned_storage</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/alignment_of.html" title="alignment_of"><span class="index-entry-level-1">alignment_of</span></a></p></li>
|
||||
</ul></div>
|
||||
</li></ul></div></dd>
|
||||
<dt>
|
||||
<a name="idx_id_20"></a><span class="term">F</span>
|
||||
</dt>
|
||||
<dd><div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none">
|
||||
|
||||
@ -24,7 +24,7 @@
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="idm1546642304"></a>Macro Index</h2></div></div></div>
|
||||
<a name="idm1547921872"></a>Macro Index</h2></div></div></div>
|
||||
<p><a class="link" href="s13.html#idx_id_31">B</a></p>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt>
|
||||
|
||||
@ -23,7 +23,7 @@
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="idm1546583296"></a>Index</h2></div></div></div>
|
||||
<a name="idm1547862864"></a>Index</h2></div></div></div>
|
||||
<p><a class="link" href="s14.html#idx_id_45">A</a> <a class="link" href="s14.html#idx_id_46">B</a> <a class="link" href="s14.html#idx_id_47">C</a> <a class="link" href="s14.html#idx_id_48">D</a> <a class="link" href="s14.html#idx_id_49">E</a> <a class="link" href="s14.html#idx_id_50">F</a> <a class="link" href="s14.html#idx_id_51">H</a> <a class="link" href="s14.html#idx_id_52">I</a> <a class="link" href="s14.html#idx_id_53">M</a> <a class="link" href="s14.html#idx_id_54">N</a> <a class="link" href="s14.html#idx_id_55">O</a> <a class="link" href="s14.html#idx_id_56">P</a> <a class="link" href="s14.html#idx_id_57">R</a> <a class="link" href="s14.html#idx_id_58">T</a> <a class="link" href="s14.html#idx_id_59">U</a></p>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt>
|
||||
@ -37,15 +37,29 @@
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/add_reference.html" title="add_reference"><span class="index-entry-level-0">add_reference</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/add_rvalue_reference.html" title="add_rvalue_reference"><span class="index-entry-level-0">add_rvalue_reference</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/add_volatile.html" title="add_volatile"><span class="index-entry-level-0">add_volatile</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/aligned_storage.html" title="aligned_storage"><span class="index-entry-level-0">aligned_storage</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none">
|
||||
<p><span class="index-entry-level-0">aligned_storage</span></p>
|
||||
<div class="index"><ul class="index" style="list-style-type: none; ">
|
||||
<li class="listitem" style="list-style-type: none"><p><span class="bold"><strong><a class="link" href="../boost_typetraits/reference/aligned_storage.html" title="aligned_storage"><span class="index-entry-level-1">aligned_storage</span></a></strong></span></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/aligned_storage.html" title="aligned_storage"><span class="index-entry-level-1">align_t</span></a></p></li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem" style="list-style-type: none">
|
||||
<p><span class="index-entry-level-0">alignment_of</span></p>
|
||||
<div class="index"><ul class="index" style="list-style-type: none; ">
|
||||
<li class="listitem" style="list-style-type: none"><p><span class="bold"><strong><a class="link" href="../boost_typetraits/reference/alignment_of.html" title="alignment_of"><span class="index-entry-level-1">alignment_of</span></a></strong></span></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/alignment_of.html" title="alignment_of"><span class="index-entry-level-1">align_t</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/alignment_of.html" title="alignment_of"><span class="index-entry-level-1">integral_constant</span></a></p></li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem" style="list-style-type: none">
|
||||
<p><span class="index-entry-level-0">align_t</span></p>
|
||||
<div class="index"><ul class="index" style="list-style-type: none; ">
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/aligned_storage.html" title="aligned_storage"><span class="index-entry-level-1">aligned_storage</span></a></p></li>
|
||||
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/reference/alignment_of.html" title="alignment_of"><span class="index-entry-level-1">alignment_of</span></a></p></li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem" style="list-style-type: none">
|
||||
<p><span class="index-entry-level-0">any</span></p>
|
||||
<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><p><a class="link" href="../boost_typetraits/category/value_traits/operators.html" title="Operator Type Traits"><span class="index-entry-level-1">Operator Type Traits</span></a></p></li></ul></div>
|
||||
</li>
|
||||
|
||||
Reference in New Issue
Block a user