Skip to content

Commit 8388b22

Browse files
TylerMSFTTylerMSFT
authored andcommitted
acrolinx
1 parent 44e66ae commit 8388b22

3 files changed

Lines changed: 12 additions & 14 deletions

File tree

‎docs/cpp/align-cpp.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,17 @@ Use `__declspec(align(#))` to precisely control the alignment of user-defined da
1919
2020
## Remarks
2121

22-
Writing applications that use the latest processor instructions introduces some new constraints and issues. Many new instructions require data that's aligned to 16-byte boundaries. Aligning frequently used data to the processor's cache line size improves cache performance. For example, if you define a structure whose size is less than 32 bytes, you may want 32-byte alignment to make sure that objects of that structure type are efficiently cached.
22+
Writing applications that use the latest processor instructions introduces some new constraints and issues. Many new instructions require data be aligned to 16-byte boundaries. Aligning frequently used data to the processor's cache line size improves cache performance. For example, if you define a structure whose size is less than 32 bytes, you might want 32-byte alignment to make sure that objects of that structure type are efficiently cached.
2323

2424
\# is the alignment value. Valid entries are integer powers of two from 1 to 8192 (bytes), such as 2, 4, 8, 16, 32, or 64. `declarator` is the data that you're declaring as aligned.
2525

2626
For information about how to return a value of type `size_t` that is the alignment requirement of the type, see [`alignof`](../cpp/alignof-operator.md). For information about how to declare unaligned pointers when targeting 64-bit processors, see [`__unaligned`](../cpp/unaligned.md).
2727

2828
You can use `__declspec(align(#))` when you define a **`struct`**, **`union`**, or **`class`**, or when you declare a variable.
2929

30-
The compiler doesn't guarantee or attempt to preserve the alignment attribute of data during a copy or data transform operation. For example, [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) can copy a struct declared with `__declspec(align(#))` to any location. Ordinary allocators (for example, [`malloc`](../c-runtime-library/reference/malloc.md), C++ [`operator new`](new-operator-cpp.md), and the Win32 allocators) typically return memory that isn't sufficiently aligned for `__declspec(align(#))` structures or arrays of structures. To guarantee that the destination of a copy or data transformation operation is correctly aligned, use [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md). Or, write your own allocator.
30+
The compiler doesn't guarantee, or attempt to preserve, the alignment attribute of data during a copy or data transform operation. For example, [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) can copy a struct declared with `__declspec(align(#))` to any location. Ordinary allocators (for example, [`malloc`](../c-runtime-library/reference/malloc.md), C++ [`operator new`](new-operator-cpp.md), and the Win32 allocators) typically return memory that isn't sufficiently aligned for `__declspec(align(#))` structures or arrays of structures. To guarantee that the destination of a copy or data transformation operation is correctly aligned, use [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md). Or, write your own allocator.
3131

32-
You can't specify alignment for function parameters. When you pass data that has an alignment attribute by value on the stack, its alignment is controlled by the calling convention. If data alignment is important in the called function, copy the parameter into correctly aligned memory before use.
32+
You can't specify alignment for function parameters. When you pass data that has an alignment attribute by value on the stack, the calling convention controls its alignment. If data alignment is important in the called function, copy the parameter into correctly aligned memory before use.
3333

3434
Without `__declspec(align(#))`, the compiler generally aligns data on natural boundaries based on the target processor and the size of the data, up to 4-byte boundaries on 32-bit processors, and 8-byte boundaries on 64-bit processors. Data in classes or structures is aligned in the class or structure at the minimum of its natural alignment and the current packing setting (from `#pragma pack` or the `/Zp` compiler option).
3535

‎docs/cpp/alignas-specifier.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ alignas(pack...)
2121

2222
You can use **`alignas`** specifier on a **`struct`**, **`class`**, **`union`**, or variable declaration.
2323

24-
For `alignas(expression)`, the expression must be an integral constant expression that is `0` or a power of 2 (1, 2, 4, 8, 16, 32, 64...). All other expressions are ill-formed.
24+
For `alignas(expression)`, the expression must be an integral constant expression that is 0 or a power of 2 (1, 2, 4, 8, 16, 32, 64...). All other expressions are ill-formed.
2525

2626
Prefer **`alignas`** over [`__declspec(align(#))`](align-cpp.md) for code portability.
2727

@@ -36,10 +36,9 @@ struct alignas(8) S1
3636
static_assert(alignof(S1) == 8, "alignof(S1) should be 8");
3737
```
3838

39-
When multiple **`alignas`** are applied to the same declaration, the one with the largest value is used.\
40-
When the **`alignas`** value is `0`, **`alignas`** is ignored.\
39+
When multiple **`alignas`** are applied to the same declaration, the one with the largest value is used. When the **`alignas`** value is `0`, **`alignas`** is ignored.
4140

42-
The following example shows how to use `alignas`:
41+
The following example shows how to use `alignas` with a user-defined type:
4342

4443
```cpp
4544
class alignas(4) alignas(16) C1 {};
@@ -61,7 +60,7 @@ static_assert(alignof(C1) == 16, "alignof(C1) should be 16");
6160
static_assert(alignof(U1) == alignof(U2), "alignof(U1) should be equivalent to alignof(U2)");
6261
```
6362
64-
Instead of using an integral constant for the alignment value, you can supply a type. The type's default alignment is used as the alignment value, as shown in the following example:
63+
You can supply a type as the alignment value. The type's default alignment is used as the alignment value, as shown in the following example:
6564
6665
```cpp
6766
struct alignas(double) S2
@@ -72,7 +71,7 @@ struct alignas(double) S2
7271
static_assert(alignof(S2) == alignof(double), "alignof(S2) should be equivalent to alignof(double)");
7372
```
7473

75-
A template parameter pack (`alignas ( pack... )`) can be used as the alignment value. Only the strictest alignment is used.
74+
A template parameter pack (`alignas ( pack... )`) can also be used as the alignment value. The largest alignment of all the elements in the pack is used.
7675

7776
```cpp
7877
template <typename... Ts>
@@ -87,7 +86,7 @@ static_assert(alignof(C2<short, int>) == 4, "alignof(C2<short, int>) should be 4
8786
static_assert(alignof(C2<int, float, double>) == 8, "alignof(C2<int, float, double>) should be 8");
8887
```
8988

90-
If multiple **`alignas`** are applied, the resulting alignment is the largest of all the **`alignas`** values, and can't be less than the natural alignment of the type it is applied to.
89+
If multiple **`alignas`** are applied, the resulting alignment is the largest of all the **`alignas`** values, and can't be less than the natural alignment of the type it's applied to.
9190
The declaration and definition of user-defined types must have the same alignment value.
9291

9392
```cpp

‎docs/cpp/alignment-cpp-declarations.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ One of the low-level features of C++ is the ability to specify the precise align
99

1010
In most scenarios, you never have to be concerned with alignment because the default alignment is already optimal. In some cases, however, you can achieve significant performance improvements, or memory savings, by specifying a custom alignment for your data structures. Before Visual Studio 2015 you could use the Microsoft-specific keywords **`__alignof`** and **`__declspec(align)`** to specify an alignment greater than the default. Starting in Visual Studio 2015 you should use the C++11 standard keywords **`alignof`** and **`alignas`** for maximum code portability. The new keywords behave in the same way under the hood as the Microsoft-specific extensions. The documentation for those extensions also applies to the new keywords. For more information, see [`alignof` Operator](../cpp/alignof-operator.md), [`alignas` Specifier](../cpp/alignas-specifier.md) and [align](../cpp/align-cpp.md). The C++ standard doesn't specify packing behavior for alignment on boundaries smaller than the compiler default for the target platform, so you still need to use the Microsoft [`#pragma pack`](../preprocessor/pack.md) in that case.
1111

12-
Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with non-trivial constructors or destructors.
12+
Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with nontrivial constructors or destructors.
1313

1414
## Alignment and memory addresses
1515

@@ -57,8 +57,7 @@ Both declarations return `sizeof(struct x_)` as 12 bytes.
5757
The second declaration includes two padding elements:
5858

5959
1. `char _pad0[3]` to align the `int b` member on a 4-byte boundary.
60-
61-
1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a four-byte boundary.
60+
1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a 4-byte boundary.
6261

6362
The padding aligns the elements of `bar[3]` in a way that allows natural access.
6463

@@ -95,7 +94,7 @@ The **`alignas`** specifier is a portable, C++ standard way to specify custom al
9594

9695
## Example
9796

98-
You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler will choose the strictest one, (the one with the largest value).
97+
You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler chooses the one with the largest value.
9998

10099
```cpp
101100
// alignas_alignof.cpp

0 commit comments

Comments
 (0)