1 //===--- TrailingObjects.h - Variable-length classes ------------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
10 /// This header defines support for implementing classes that have
11 /// some trailing object (or arrays of objects) appended to them. The
12 /// main purpose is to make it obvious where this idiom is being used,
13 /// and to make the usage more idiomatic and more difficult to get
16 /// The TrailingObject template abstracts away the reinterpret_cast,
17 /// pointer arithmetic, and size calculations used for the allocation
18 /// and access of appended arrays of objects, and takes care that they
19 /// are all allocated at their required alignment. Additionally, it
20 /// ensures that the base type is final -- deriving from a class that
21 /// expects data appended immediately after it is typically not safe.
23 /// Users are expected to derive from this template, and provide
24 /// numTrailingObjects implementations for each trailing type except
25 /// the last, e.g. like this sample:
28 /// class VarLengthObj : private TrailingObjects<VarLengthObj, int, double> {
29 /// friend TrailingObjects;
31 /// unsigned NumInts, NumDoubles;
32 /// size_t numTrailingObjects(OverloadToken<int>) const { return NumInts; }
36 /// You can access the appended arrays via 'getTrailingObjects', and
37 /// determine the size needed for allocation via
38 /// 'additionalSizeToAlloc' and 'totalSizeToAlloc'.
40 /// All the methods implemented by this class are are intended for use
41 /// by the implementation of the class, not as part of its interface
42 /// (thus, private inheritance is suggested).
44 //===----------------------------------------------------------------------===//
46 #ifndef LLVM_SUPPORT_TRAILINGOBJECTS_H
47 #define LLVM_SUPPORT_TRAILINGOBJECTS_H
49 #include "llvm/Support/AlignOf.h"
50 #include "llvm/Support/Compiler.h"
51 #include "llvm/Support/MathExtras.h"
52 #include "llvm/Support/type_traits.h"
54 #include <type_traits>
58 namespace trailing_objects_internal
{
59 /// Helper template to calculate the max alignment requirement for a set of
61 template <typename First
, typename
... Rest
> class AlignmentCalcHelper
{
64 FirstAlignment
= alignof(First
),
65 RestAlignment
= AlignmentCalcHelper
<Rest
...>::Alignment
,
70 Alignment
= FirstAlignment
> RestAlignment
? FirstAlignment
: RestAlignment
74 template <typename First
> class AlignmentCalcHelper
<First
> {
76 enum { Alignment
= alignof(First
) };
79 /// The base class for TrailingObjects* classes.
80 class TrailingObjectsBase
{
82 /// OverloadToken's purpose is to allow specifying function overloads
83 /// for different types, without actually taking the types as
84 /// parameters. (Necessary because member function templates cannot
85 /// be specialized, so overloads must be used instead of
87 template <typename T
> struct OverloadToken
{};
91 class TrailingObjectsAligner
: public TrailingObjectsBase
{};
93 class alignas(1) TrailingObjectsAligner
<1> : public TrailingObjectsBase
{};
95 class alignas(2) TrailingObjectsAligner
<2> : public TrailingObjectsBase
{};
97 class alignas(4) TrailingObjectsAligner
<4> : public TrailingObjectsBase
{};
99 class alignas(8) TrailingObjectsAligner
<8> : public TrailingObjectsBase
{};
101 class alignas(16) TrailingObjectsAligner
<16> : public TrailingObjectsBase
{
104 class alignas(32) TrailingObjectsAligner
<32> : public TrailingObjectsBase
{
107 // Just a little helper for transforming a type pack into the same
108 // number of a different type. e.g.:
109 // ExtractSecondType<Foo..., int>::type
110 template <typename Ty1
, typename Ty2
> struct ExtractSecondType
{
114 // TrailingObjectsImpl is somewhat complicated, because it is a
115 // recursively inheriting template, in order to handle the template
116 // varargs. Each level of inheritance picks off a single trailing type
117 // then recurses on the rest. The "Align", "BaseTy", and
118 // "TopTrailingObj" arguments are passed through unchanged through the
119 // recursion. "PrevTy" is, at each level, the type handled by the
120 // level right above it.
122 template <int Align
, typename BaseTy
, typename TopTrailingObj
, typename PrevTy
,
124 class TrailingObjectsImpl
{
125 // The main template definition is never used -- the two
126 // specializations cover all possibilities.
129 template <int Align
, typename BaseTy
, typename TopTrailingObj
, typename PrevTy
,
130 typename NextTy
, typename
... MoreTys
>
131 class TrailingObjectsImpl
<Align
, BaseTy
, TopTrailingObj
, PrevTy
, NextTy
,
133 : public TrailingObjectsImpl
<Align
, BaseTy
, TopTrailingObj
, NextTy
,
136 typedef TrailingObjectsImpl
<Align
, BaseTy
, TopTrailingObj
, NextTy
, MoreTys
...>
139 struct RequiresRealignment
{
140 static const bool value
= alignof(PrevTy
) < alignof(NextTy
);
143 static constexpr bool requiresRealignment() {
144 return RequiresRealignment::value
;
148 // Ensure the inherited getTrailingObjectsImpl is not hidden.
149 using ParentType::getTrailingObjectsImpl
;
151 // These two functions are helper functions for
152 // TrailingObjects::getTrailingObjects. They recurse to the left --
153 // the result for each type in the list of trailing types depends on
154 // the result of calling the function on the type to the
155 // left. However, the function for the type to the left is
156 // implemented by a *subclass* of this class, so we invoke it via
157 // the TopTrailingObj, which is, via the
158 // curiously-recurring-template-pattern, the most-derived type in
159 // this recursion, and thus, contains all the overloads.
160 static const NextTy
*
161 getTrailingObjectsImpl(const BaseTy
*Obj
,
162 TrailingObjectsBase::OverloadToken
<NextTy
>) {
163 auto *Ptr
= TopTrailingObj::getTrailingObjectsImpl(
164 Obj
, TrailingObjectsBase::OverloadToken
<PrevTy
>()) +
165 TopTrailingObj::callNumTrailingObjects(
166 Obj
, TrailingObjectsBase::OverloadToken
<PrevTy
>());
168 if (requiresRealignment())
169 return reinterpret_cast<const NextTy
*>(
170 llvm::alignAddr(Ptr
, alignof(NextTy
)));
172 return reinterpret_cast<const NextTy
*>(Ptr
);
176 getTrailingObjectsImpl(BaseTy
*Obj
,
177 TrailingObjectsBase::OverloadToken
<NextTy
>) {
178 auto *Ptr
= TopTrailingObj::getTrailingObjectsImpl(
179 Obj
, TrailingObjectsBase::OverloadToken
<PrevTy
>()) +
180 TopTrailingObj::callNumTrailingObjects(
181 Obj
, TrailingObjectsBase::OverloadToken
<PrevTy
>());
183 if (requiresRealignment())
184 return reinterpret_cast<NextTy
*>(llvm::alignAddr(Ptr
, alignof(NextTy
)));
186 return reinterpret_cast<NextTy
*>(Ptr
);
189 // Helper function for TrailingObjects::additionalSizeToAlloc: this
190 // function recurses to superclasses, each of which requires one
191 // fewer size_t argument, and adds its own size.
192 static constexpr size_t additionalSizeToAllocImpl(
193 size_t SizeSoFar
, size_t Count1
,
194 typename ExtractSecondType
<MoreTys
, size_t>::type
... MoreCounts
) {
195 return ParentType::additionalSizeToAllocImpl(
196 (requiresRealignment() ? llvm::alignTo
<alignof(NextTy
)>(SizeSoFar
)
198 sizeof(NextTy
) * Count1
,
203 // The base case of the TrailingObjectsImpl inheritance recursion,
204 // when there's no more trailing types.
205 template <int Align
, typename BaseTy
, typename TopTrailingObj
, typename PrevTy
>
206 class TrailingObjectsImpl
<Align
, BaseTy
, TopTrailingObj
, PrevTy
>
207 : public TrailingObjectsAligner
<Align
> {
209 // This is a dummy method, only here so the "using" doesn't fail --
210 // it will never be called, because this function recurses backwards
211 // up the inheritance chain to subclasses.
212 static void getTrailingObjectsImpl();
214 static constexpr size_t additionalSizeToAllocImpl(size_t SizeSoFar
) {
218 template <bool CheckAlignment
> static void verifyTrailingObjectsAlignment() {}
221 } // end namespace trailing_objects_internal
223 // Finally, the main type defined in this file, the one intended for users...
225 /// See the file comment for details on the usage of the
226 /// TrailingObjects type.
227 template <typename BaseTy
, typename
... TrailingTys
>
228 class TrailingObjects
: private trailing_objects_internal::TrailingObjectsImpl
<
229 trailing_objects_internal::AlignmentCalcHelper
<
230 TrailingTys
...>::Alignment
,
231 BaseTy
, TrailingObjects
<BaseTy
, TrailingTys
...>,
232 BaseTy
, TrailingTys
...> {
234 template <int A
, typename B
, typename T
, typename P
, typename
... M
>
235 friend class trailing_objects_internal::TrailingObjectsImpl
;
237 template <typename
... Tys
> class Foo
{};
239 typedef trailing_objects_internal::TrailingObjectsImpl
<
240 trailing_objects_internal::AlignmentCalcHelper
<TrailingTys
...>::Alignment
,
241 BaseTy
, TrailingObjects
<BaseTy
, TrailingTys
...>, BaseTy
, TrailingTys
...>
243 using TrailingObjectsBase
= trailing_objects_internal::TrailingObjectsBase
;
245 using ParentType::getTrailingObjectsImpl
;
247 // This function contains only a static_assert BaseTy is final. The
248 // static_assert must be in a function, and not at class-level
249 // because BaseTy isn't complete at class instantiation time, but
250 // will be by the time this function is instantiated.
251 static void verifyTrailingObjectsAssertions() {
252 static_assert(std::is_final
<BaseTy
>(), "BaseTy must be final.");
255 // These two methods are the base of the recursion for this method.
256 static const BaseTy
*
257 getTrailingObjectsImpl(const BaseTy
*Obj
,
258 TrailingObjectsBase::OverloadToken
<BaseTy
>) {
263 getTrailingObjectsImpl(BaseTy
*Obj
,
264 TrailingObjectsBase::OverloadToken
<BaseTy
>) {
268 // callNumTrailingObjects simply calls numTrailingObjects on the
269 // provided Obj -- except when the type being queried is BaseTy
270 // itself. There is always only one of the base object, so that case
271 // is handled here. (An additional benefit of indirecting through
272 // this function is that consumers only say "friend
273 // TrailingObjects", and thus, only this class itself can call the
274 // numTrailingObjects function.)
276 callNumTrailingObjects(const BaseTy
*Obj
,
277 TrailingObjectsBase::OverloadToken
<BaseTy
>) {
281 template <typename T
>
282 static size_t callNumTrailingObjects(const BaseTy
*Obj
,
283 TrailingObjectsBase::OverloadToken
<T
>) {
284 return Obj
->numTrailingObjects(TrailingObjectsBase::OverloadToken
<T
>());
288 // Make this (privately inherited) member public.
290 using ParentType::OverloadToken
;
292 // MSVC bug prevents the above from working, at least up through CL
294 template <typename T
>
295 using OverloadToken
= typename
ParentType::template OverloadToken
<T
>;
298 /// Returns a pointer to the trailing object array of the given type
299 /// (which must be one of those specified in the class template). The
300 /// array may have zero or more elements in it.
301 template <typename T
> const T
*getTrailingObjects() const {
302 verifyTrailingObjectsAssertions();
303 // Forwards to an impl function with overloads, since member
304 // function templates can't be specialized.
305 return this->getTrailingObjectsImpl(
306 static_cast<const BaseTy
*>(this),
307 TrailingObjectsBase::OverloadToken
<T
>());
310 /// Returns a pointer to the trailing object array of the given type
311 /// (which must be one of those specified in the class template). The
312 /// array may have zero or more elements in it.
313 template <typename T
> T
*getTrailingObjects() {
314 verifyTrailingObjectsAssertions();
315 // Forwards to an impl function with overloads, since member
316 // function templates can't be specialized.
317 return this->getTrailingObjectsImpl(
318 static_cast<BaseTy
*>(this), TrailingObjectsBase::OverloadToken
<T
>());
321 /// Returns the size of the trailing data, if an object were
322 /// allocated with the given counts (The counts are in the same order
323 /// as the template arguments). This does not include the size of the
324 /// base object. The template arguments must be the same as those
325 /// used in the class; they are supplied here redundantly only so
326 /// that it's clear what the counts are counting in callers.
327 template <typename
... Tys
>
328 static constexpr typename
std::enable_if
<
329 std::is_same
<Foo
<TrailingTys
...>, Foo
<Tys
...>>::value
, size_t>::type
330 additionalSizeToAlloc(typename
trailing_objects_internal::ExtractSecondType
<
331 TrailingTys
, size_t>::type
... Counts
) {
332 return ParentType::additionalSizeToAllocImpl(0, Counts
...);
335 /// Returns the total size of an object if it were allocated with the
336 /// given trailing object counts. This is the same as
337 /// additionalSizeToAlloc, except it *does* include the size of the base
339 template <typename
... Tys
>
340 static constexpr typename
std::enable_if
<
341 std::is_same
<Foo
<TrailingTys
...>, Foo
<Tys
...>>::value
, size_t>::type
342 totalSizeToAlloc(typename
trailing_objects_internal::ExtractSecondType
<
343 TrailingTys
, size_t>::type
... Counts
) {
344 return sizeof(BaseTy
) + ParentType::additionalSizeToAllocImpl(0, Counts
...);
347 /// A type where its ::with_counts template member has a ::type member
348 /// suitable for use as uninitialized storage for an object with the given
349 /// trailing object counts. The template arguments are similar to those
350 /// of additionalSizeToAlloc.
352 /// Use with FixedSizeStorageOwner, e.g.:
356 /// MyObj::FixedSizeStorage<void *>::with_counts<1u>::type myStackObjStorage;
357 /// MyObj::FixedSizeStorageOwner
358 /// myStackObjOwner(new ((void *)&myStackObjStorage) MyObj);
359 /// MyObj *const myStackObjPtr = myStackObjOwner.get();
362 template <typename
... Tys
> struct FixedSizeStorage
{
363 template <size_t... Counts
> struct with_counts
{
364 enum { Size
= totalSizeToAlloc
<Tys
...>(Counts
...) };
366 alignas(BaseTy
) char buffer
[Size
];
371 /// A type that acts as the owner for an object placed into fixed storage.
372 class FixedSizeStorageOwner
{
374 FixedSizeStorageOwner(BaseTy
*p
) : p(p
) {}
375 ~FixedSizeStorageOwner() {
376 assert(p
&& "FixedSizeStorageOwner owns null?");
380 BaseTy
*get() { return p
; }
381 const BaseTy
*get() const { return p
; }
384 FixedSizeStorageOwner(const FixedSizeStorageOwner
&) = delete;
385 FixedSizeStorageOwner(FixedSizeStorageOwner
&&) = delete;
386 FixedSizeStorageOwner
&operator=(const FixedSizeStorageOwner
&) = delete;
387 FixedSizeStorageOwner
&operator=(FixedSizeStorageOwner
&&) = delete;
393 } // end namespace llvm