8297912: HotSpot Style Guide should permit alignas (Second Proposal A…

…ttempt)

Reviewed-by: kbarrett, stuefe, kvn

doc/hotspot-style.html

@@ -72,6 +72,7 @@ <h1 class="title">HotSpot Coding Style</h1>
 <li><a href="#expression-sfinae" id="toc-expression-sfinae">Expression
 SFINAE</a></li>
 <li><a href="#enum" id="toc-enum">enum</a></li>
+<li><a href="#alignas" id="toc-alignas">alignas</a></li>
 <li><a href="#thread_local" id="toc-thread_local">thread_local</a></li>
 <li><a href="#nullptr" id="toc-nullptr">nullptr</a></li>
 <li><a href="#atomic" id="toc-atomic">&lt;atomic&gt;</a></li>
@@ -598,7 +599,7 @@ <h3 id="c-standard-library">C++ Standard Library</h3>
 <code>std::numeric_limits</code>.</li>
 <li><code>#include &lt;type_traits&gt;</code>.</li>
 <li><code>#include &lt;cstddef&gt;</code> to use
-<code>std::nullptr_t</code>.</li>
+<code>std::nullptr_t</code> and <code>std::max_align_t</code>.</li>
 </ul>
 <p>TODO: Rather than directly #including (permitted) Standard Library
 headers, use a convention of #including wrapper headers (in some
@@ -670,6 +671,53 @@ <h3 id="enum">enum</h3>
 constant members. Compilers having such bugs are no longer supported.
 Except where an enum is semantically appropriate, new code should use
 integral constants.</p>
+<h3 id="alignas">alignas</h3>
+<p><em>Alignment-specifiers</em> (<code>alignas</code> <a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf">n2341</a>)
+are permitted, with restrictions.</p>
+<p><em>Alignment-specifiers</em> are permitted when the requested
+alignment is a <em>fundamental alignment</em> (not greater than
+<code>alignof(std::max_align_t)</code> <a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf">C++14
+3.11/2</a>).</p>
+<p><em>Alignment-specifiers</em> with an <em>extended alignment</em>
+(greater than <code>alignof(std::max_align_t)</code> <a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf">C++14
+3.11/3</a>) may only be used to align variables with static or automatic
+storage duration (<a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf">C++14
+3.7.1, 3.7.3</a>). As a consequence, <em>over-aligned types</em> are
+forbidden; this may change if HotSpot updates to using C++17 or later
+(<a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0035r4.html">p0035r4</a>).</p>
+<p>Large <em>extended alignments</em> should be avoided, particularly
+for stack allocated objects. What is a large value may depend on the
+platform and configuration. There may also be hard limits for some
+platforms.</p>
+<p>An <em>alignment-specifier</em> must always be applied to a
+definition (<a
+href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf">C++14
+10.6.2/6</a>). (C++ allows an <em>alignment-specifier</em> to optionally
+also be applied to a declaration, so long as the definition has
+equivalent alignment. There isn't any known benefit from duplicating the
+alignment in a non-definition declaration, so such duplication should be
+avoided in HotSpot code.)</p>
+<p>Enumerations are forbidden from having <em>alignment-specifiers</em>.
+Aligned enumerations were originally permitted but insufficiently
+specified, and were later (C++20) removed (<a
+href="https://cplusplus.github.io/CWG/issues/2354.html">CWG 2354</a>).
+Permitting such usage in HotSpot now would just cause problems in the
+future.</p>
+<p><em>Alignment-specifiers</em> are forbidden in <code>typedef</code>
+and <em>alias-declarations</em>. This may work or may have worked in
+some versions of some compilers, but was later (C++14) explicitly
+disallowed (<a
+href="https://cplusplus.github.io/CWG/issues/1437.html">CWG
+1437</a>).</p>
+<p>The HotSpot macro <code>ATTRIBUTE_ALIGNED</code> provides similar
+capabilities for platforms that define it. This macro predates the use
+by HotSpot of C++ versions providing <code>alignas</code>. New code
+should use <code>alignas</code>.</p>
 <h3 id="thread_local">thread_local</h3>
 <p>Avoid use of <code>thread_local</code> (<a
 href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm">n2659</a>);

doc/hotspot-style.md

@@ -573,7 +573,7 @@ There are a few exceptions to this rule.
 * `#include <new>` to use placement `new`, `std::nothrow`, and `std::nothrow_t`.
 * `#include <limits>` to use `std::numeric_limits`.
 * `#include <type_traits>`.
-* `#include <cstddef>` to use `std::nullptr_t`.
+* `#include <cstddef>` to use `std::nullptr_t` and `std::max_align_t`.
 
 TODO: Rather than directly \#including (permitted) Standard Library
 headers, use a convention of \#including wrapper headers (in some
@@ -651,6 +651,51 @@ constant members.  Compilers having such bugs are no longer supported.
 Except where an enum is semantically appropriate, new code should use
 integral constants.
 
+### alignas
+
+_Alignment-specifiers_ (`alignas`
+[n2341](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf))
+are permitted, with restrictions.
+
+_Alignment-specifiers_ are permitted when the requested alignment is a
+_fundamental alignment_ (not greater than `alignof(std::max_align_t)`
+[C++14 3.11/2](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf)).
+
+_Alignment-specifiers_ with an _extended alignment_ (greater than
+`alignof(std::max_align_t)`
+[C++14 3.11/3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf))
+may only be used to align variables with static or automatic storage duration
+([C++14 3.7.1, 3.7.3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf)).
+As a consequence, _over-aligned types_ are forbidden; this may change if
+HotSpot updates to using C++17 or later
+([p0035r4](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0035r4.html)).
+
+Large _extended alignments_ should be avoided, particularly for stack
+allocated objects. What is a large value may depend on the platform and
+configuration. There may also be hard limits for some platforms.
+
+An _alignment-specifier_ must always be applied to a definition
+([C++14 10.6.2/6](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf)).
+(C++ allows an _alignment-specifier_ to optionally also be applied to a
+declaration, so long as the definition has equivalent alignment. There isn't
+any known benefit from duplicating the alignment in a non-definition
+declaration, so such duplication should be avoided in HotSpot code.)
+
+Enumerations are forbidden from having _alignment-specifiers_. Aligned
+enumerations were originally permitted but insufficiently specified, and were
+later (C++20) removed
+([CWG 2354](https://cplusplus.github.io/CWG/issues/2354.html)).
+Permitting such usage in HotSpot now would just cause problems in the future.
+
+_Alignment-specifiers_ are forbidden in `typedef` and _alias-declarations_.
+This may work or may have worked in some versions of some compilers, but was
+later (C++14) explicitly disallowed
+([CWG 1437](https://cplusplus.github.io/CWG/issues/1437.html)).
+
+The HotSpot macro `ATTRIBUTE_ALIGNED` provides similar capabilities for
+platforms that define it. This macro predates the use by HotSpot of C++
+versions providing `alignas`. New code should use `alignas`.
+
 ### thread_local
 
 Avoid use of `thread_local`