You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8388b22
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/cpp/align-cpp.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,17 +19,17 @@ Use `__declspec(align(#))` to precisely control the alignment of user-defined da
19
19
20
20
## Remarks
21
21
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.
23
23
24
24
\# 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.
25
25
26
26
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).
27
27
28
28
You can use `__declspec(align(#))` when you define a **`struct`**, **`union`**, or **`class`**, or when you declare a variable.
29
29
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.
31
31
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.
33
33
34
34
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).
Copy file name to clipboardExpand all lines: docs/cpp/alignas-specifier.md
+6-7Lines changed: 6 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ alignas(pack...)
21
21
22
22
You can use **`alignas`** specifier on a **`struct`**, **`class`**, **`union`**, or variable declaration.
23
23
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.
25
25
26
26
Prefer **`alignas`** over [`__declspec(align(#))`](align-cpp.md) for code portability.
27
27
@@ -36,10 +36,9 @@ struct alignas(8) S1
36
36
static_assert(alignof(S1) == 8, "alignof(S1) should be 8");
37
37
```
38
38
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.
41
40
42
-
The following example shows how to use `alignas`:
41
+
The following example shows how to use `alignas` with a user-defined type:
43
42
44
43
```cpp
45
44
classalignas(4) alignas(16) C1 {};
@@ -61,7 +60,7 @@ static_assert(alignof(C1) == 16, "alignof(C1) should be 16");
61
60
static_assert(alignof(U1) == alignof(U2), "alignof(U1) should be equivalent to alignof(U2)");
62
61
```
63
62
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:
65
64
66
65
```cpp
67
66
struct alignas(double) S2
@@ -72,7 +71,7 @@ struct alignas(double) S2
72
71
static_assert(alignof(S2) == alignof(double), "alignof(S2) should be equivalent to alignof(double)");
73
72
```
74
73
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.
76
75
77
76
```cpp
78
77
template <typename... Ts>
@@ -87,7 +86,7 @@ static_assert(alignof(C2<short, int>) == 4, "alignof(C2<short, int>) should be 4
87
86
static_assert(alignof(C2<int, float, double>) == 8, "alignof(C2<int, float, double>) should be 8");
88
87
```
89
88
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.
91
90
The declaration and definition of user-defined types must have the same alignment value.
Copy file name to clipboardExpand all lines: docs/cpp/alignment-cpp-declarations.md
+3-4Lines changed: 3 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ One of the low-level features of C++ is the ability to specify the precise align
9
9
10
10
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.
11
11
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.
13
13
14
14
## Alignment and memory addresses
15
15
@@ -57,8 +57,7 @@ Both declarations return `sizeof(struct x_)` as 12 bytes.
57
57
The second declaration includes two padding elements:
58
58
59
59
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.
62
61
63
62
The padding aligns the elements of `bar[3]` in a way that allows natural access.
64
63
@@ -95,7 +94,7 @@ The **`alignas`** specifier is a portable, C++ standard way to specify custom al
95
94
96
95
## Example
97
96
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 onewith the largest value.
0 commit comments