From Jason Turner

[mdspan.accessor.aligned]

C++23 → Trunk 4.9 KB 148 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpckmf72fc/{from.md → to.md} +145 -0
tmp/tmpckmf72fc/{from.md → to.md} RENAMED
@@ -0,0 +1,145 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ##### Class template `aligned_accessor` <a id="mdspan.accessor.aligned">[[mdspan.accessor.aligned]]</a>
2
+
3
+ ###### Overview <a id="mdspan.accessor.aligned.overview">[[mdspan.accessor.aligned.overview]]</a>
4
+
5
+ ``` cpp
6
+ namespace std {
7
+ template<class ElementType, size_t ByteAlignment>
8
+ struct aligned_accessor {
9
+ using offset_policy = default_accessor<ElementType>;
10
+ using element_type = ElementType;
11
+ using reference = ElementType&;
12
+ using data_handle_type = ElementType*;
13
+
14
+ static constexpr size_t byte_alignment = ByteAlignment;
15
+
16
+ constexpr aligned_accessor() noexcept = default;
17
+ template<class OtherElementType, size_t OtherByteAlignment>
18
+ constexpr aligned_accessor(
19
+ aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept;
20
+ template<class OtherElementType>
21
+ constexpr explicit aligned_accessor(default_accessor<OtherElementType>) noexcept;
22
+
23
+ template<class OtherElementType>
24
+ constexpr operator default_accessor<OtherElementType>() const noexcept;
25
+
26
+ constexpr reference access(data_handle_type p, size_t i) const noexcept;
27
+
28
+ constexpr typename offset_policy::data_handle_type offset(
29
+ data_handle_type p, size_t i) const noexcept;
30
+ };
31
+ }
32
+ ```
33
+
34
+ *Mandates:*
35
+
36
+ - `byte_alignment` is a power of two, and
37
+ - `byte_alignment >= alignof(ElementType)` is `true`.
38
+
39
+ `aligned_accessor` meets the accessor policy requirements.
40
+
41
+ `ElementType` is required to be a complete object type that is neither
42
+ an abstract class type nor an array type.
43
+
44
+ Each specialization of `aligned_accessor` is a trivially copyable type
45
+ that models `semiregular`.
46
+
47
+ \[`0`, n) is an accessible range for an object `p` of type
48
+ `data_handle_type` and an object of type `aligned_accessor` if and only
49
+ if
50
+
51
+ - \[`p`, `p + `n) is a valid range, and,
52
+ - if n is greater than zero, then
53
+ `is_sufficiently_aligned<byte_alignment>(p)` is `true`.
54
+
55
+ [*Example 1*:
56
+
57
+ The following function `compute` uses `is_sufficiently_aligned` to check
58
+ whether a given `mdspan` with `default_accessor` has a data handle with
59
+ sufficient alignment to be used with
60
+ `aligned_accessor<float, 4 * sizeof(float)>`. If so, the function
61
+ dispatches to a function `compute_using_fourfold_overalignment` that
62
+ requires fourfold over-alignment of arrays, but can therefore use
63
+ hardware-specific instructions, such as four-wide SIMD (Single
64
+ Instruction Multiple Data) instructions. Otherwise, `compute` dispatches
65
+ to a possibly less optimized function
66
+ `compute_without_requiring_overalignment` that has no over-alignment
67
+ requirement.
68
+
69
+ ``` cpp
70
+ void compute_using_fourfold_overalignment(
71
+ mdspan<float, dims<1>, layout_right, aligned_accessor<float, 4 * alignof(float)>> x);
72
+
73
+ void compute_without_requiring_overalignment(
74
+ mdspan<float, dims<1>, layout_right> x);
75
+
76
+ void compute(mdspan<float, dims<1>> x) {
77
+ constexpr auto byte_alignment = 4 * sizeof(float);
78
+ auto accessor = aligned_accessor<float, byte_alignment>{};
79
+ auto x_handle = x.data_handle();
80
+
81
+ if (is_sufficiently_aligned<byte_alignment>(x_handle)) {
82
+ compute_using_fourfold_overalignment(mdspan{x_handle, x.mapping(), accessor});
83
+ } else {
84
+ compute_without_requiring_overalignment(x);
85
+ }
86
+ }
87
+ ```
88
+
89
+ — *end example*]
90
+
91
+ ###### Members <a id="mdspan.accessor.aligned.members">[[mdspan.accessor.aligned.members]]</a>
92
+
93
+ ``` cpp
94
+ template<class OtherElementType, size_t OtherByteAlignment>
95
+ constexpr aligned_accessor(aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept;
96
+ ```
97
+
98
+ *Constraints:*
99
+
100
+ - `is_convertible_v<OtherElementType(*)[], element_type(*)[]>` is
101
+ `true`.
102
+ - `OtherByteAlignment >= byte_alignment` is `true`.
103
+
104
+ *Effects:* None.
105
+
106
+ ``` cpp
107
+ template<class OtherElementType>
108
+ constexpr explicit aligned_accessor(default_accessor<OtherElementType>) noexcept;
109
+ ```
110
+
111
+ *Constraints:*
112
+ `is_convertible_v<OtherElementType(*)[], element_type(*)[]>` is `true`.
113
+
114
+ *Effects:* None.
115
+
116
+ ``` cpp
117
+ constexpr reference access(data_handle_type p, size_t i) const noexcept;
118
+ ```
119
+
120
+ *Preconditions:* \[`0`, `i + 1`) is an accessible range for `p` and
121
+ `*this`.
122
+
123
+ *Effects:* Equivalent to: `return assume_aligned<byte_alignment>(p)[i];`
124
+
125
+ ``` cpp
126
+ template<class OtherElementType>
127
+ constexpr operator default_accessor<OtherElementType>() const noexcept;
128
+ ```
129
+
130
+ *Constraints:*
131
+ `is_convertible_v<element_type(*)[], OtherElementType(*)[]>` is `true`.
132
+
133
+ *Effects:* Equivalent to: `return {};`
134
+
135
+ ``` cpp
136
+ constexpr typename offset_policy::data_handle_type
137
+ offset(data_handle_type p, size_t i) const noexcept;
138
+ ```
139
+
140
+ *Preconditions:* \[`0`, `i + 1`) is an accessible range for `p` and
141
+ `*this`.
142
+
143
+ *Effects:* Equivalent to:
144
+ `return assume_aligned<byte_alignment>(p) + i;`
145
+