//===--- TrailingObjects.h - Variable-length classes ------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
///
/// \file
/// This header defines support for implementing classes that have
/// some trailing object (or arrays of objects) appended to them. The
/// main purpose is to make it obvious where this idiom is being used,
/// and to make the usage more idiomatic and more difficult to get
/// wrong.
///
/// The TrailingObject template abstracts away the reinterpret_cast,
/// pointer arithmetic, and size calculations used for the allocation
/// and access of appended arrays of objects, and takes care that they
/// are all allocated at their required alignment. Additionally, it
/// ensures that the base type is final -- deriving from a class that
/// expects data appended immediately after it is typically not safe.
///
/// Users are expected to derive from this template, and provide
/// numTrailingObjects implementations for each trailing type except
/// the last, e.g. like this sample:
///
/// \code
/// class VarLengthObj : private TrailingObjects<VarLengthObj, int, double> {
/// friend TrailingObjects;
///
/// unsigned NumInts, NumDoubles;
/// size_t numTrailingObjects(OverloadToken<int>) const { return NumInts; }
/// };
/// \endcode
///
/// You can access the appended arrays via 'getTrailingObjects', and
/// determine the size needed for allocation via
/// 'additionalSizeToAlloc' and 'totalSizeToAlloc'.
///
/// All the methods implemented by this class are are intended for use
/// by the implementation of the class, not as part of its interface
/// (thus, private inheritance is suggested).
///
//===----------------------------------------------------------------------===//
#ifndef LLVM_SUPPORT_TRAILINGOBJECTS_H
#define LLVM_SUPPORT_TRAILINGOBJECTS_H
#include "llvm/Support/AlignOf.h"
#include "llvm/Support/Alignment.h"
#include "llvm/Support/Compiler.h"
#include "llvm/Support/MathExtras.h"
#include "llvm/Support/type_traits.h"
#include <new>
#include <type_traits>
namespace llvm {
namespace trailing_objects_internal {
/// Helper template to calculate the max alignment requirement for a set of
/// objects.
template <typename First, typename... Rest> class AlignmentCalcHelper {
private:
enum {
FirstAlignment = alignof(First),
RestAlignment = AlignmentCalcHelper<Rest...>::Alignment,
};
public:
enum {
Alignment = FirstAlignment > RestAlignment ? FirstAlignment : RestAlignment
};
};
template <typename First> class AlignmentCalcHelper<First> {
public:
enum { Alignment = alignof(First) };
};
/// The base class for TrailingObjects* classes.
class TrailingObjectsBase {
protected:
/// OverloadToken's purpose is to allow specifying function overloads
/// for different types, without actually taking the types as
/// parameters. (Necessary because member function templates cannot
/// be specialized, so overloads must be used instead of
/// specialization.)
template <typename T> struct OverloadToken {};
};
// Just a little helper for transforming a type pack into the same
// number of a different type. e.g.:
// ExtractSecondType<Foo..., int>::type
template <typename Ty1, typename Ty2> struct ExtractSecondType {
typedef Ty2 type;
};
// TrailingObjectsImpl is somewhat complicated, because it is a
// recursively inheriting template, in order to handle the template
// varargs. Each level of inheritance picks off a single trailing type
// then recurses on the rest. The "Align", "BaseTy", and
// "TopTrailingObj" arguments are passed through unchanged through the
// recursion. "PrevTy" is, at each level, the type handled by the
// level right above it.
template <int Align, typename BaseTy, typename TopTrailingObj, typename PrevTy,
typename... MoreTys>
class TrailingObjectsImpl {
// The main template definition is never used -- the two
// specializations cover all possibilities.
};
template <int Align, typename BaseTy, typename TopTrailingObj, typename PrevTy,
typename NextTy, typename... MoreTys>
class TrailingObjectsImpl<Align, BaseTy, TopTrailingObj, PrevTy, NextTy,
MoreTys...>
: public TrailingObjectsImpl<Align, BaseTy, TopTrailingObj, NextTy,
MoreTys...> {
typedef TrailingObjectsImpl<Align, BaseTy, TopTrailingObj, NextTy, MoreTys...>
ParentType;
struct RequiresRealignment {
static const bool value = alignof(PrevTy) < alignof(NextTy);
};
static constexpr bool requiresRealignment() {
return RequiresRealignment::value;
}
protected:
// Ensure the inherited getTrailingObjectsImpl is not hidden.
using ParentType::getTrailingObjectsImpl;
// These two functions are helper functions for
// TrailingObjects::getTrailingObjects. They recurse to the left --
// the result for each type in the list of trailing types depends on
// the result of calling the function on the type to the
// left. However, the function for the type to the left is
// implemented by a *subclass* of this class, so we invoke it via
// the TopTrailingObj, which is, via the
// curiously-recurring-template-pattern, the most-derived type in
// this recursion, and thus, contains all the overloads.
static const NextTy *
getTrailingObjectsImpl(const BaseTy *Obj,
TrailingObjectsBase::OverloadToken<NextTy>) {
auto *Ptr = TopTrailingObj::getTrailingObjectsImpl(
Obj, TrailingObjectsBase::OverloadToken<PrevTy>()) +
TopTrailingObj::callNumTrailingObjects(
Obj, TrailingObjectsBase::OverloadToken<PrevTy>());
if (requiresRealignment())
return reinterpret_cast<const NextTy *>(
alignAddr(Ptr, Align::Of<NextTy>()));
else
return reinterpret_cast<const NextTy *>(Ptr);
}
static NextTy *
getTrailingObjectsImpl(BaseTy *Obj,
TrailingObjectsBase::OverloadToken<NextTy>) {
auto *Ptr = TopTrailingObj::getTrailingObjectsImpl(
Obj, TrailingObjectsBase::OverloadToken<PrevTy>()) +
TopTrailingObj::callNumTrailingObjects(
Obj, TrailingObjectsBase::OverloadToken<PrevTy>());
if (requiresRealignment())
return reinterpret_cast<NextTy *>(alignAddr(Ptr, Align::Of<NextTy>()));
else
return reinterpret_cast<NextTy *>(Ptr);
}
// Helper function for TrailingObjects::additionalSizeToAlloc: this
// function recurses to superclasses, each of which requires one
// fewer size_t argument, and adds its own size.
static constexpr size_t additionalSizeToAllocImpl(
size_t SizeSoFar, size_t Count1,
typename ExtractSecondType<MoreTys, size_t>::type... MoreCounts) {
return ParentType::additionalSizeToAllocImpl(
(requiresRealignment() ? llvm::alignTo<alignof(NextTy)>(SizeSoFar)
: SizeSoFar) +
sizeof(NextTy) * Count1,
MoreCounts...);
}
};
// The base case of the TrailingObjectsImpl inheritance recursion,
// when there's no more trailing types.
template <int Align, typename BaseTy, typename TopTrailingObj, typename PrevTy>
class alignas(Align) TrailingObjectsImpl<Align, BaseTy, TopTrailingObj, PrevTy>
: public TrailingObjectsBase {
protected:
// This is a dummy method, only here so the "using" doesn't fail --
// it will never be called, because this function recurses backwards
// up the inheritance chain to subclasses.
static void getTrailingObjectsImpl();
static constexpr size_t additionalSizeToAllocImpl(size_t SizeSoFar) {
return SizeSoFar;
}
template <bool CheckAlignment> static void verifyTrailingObjectsAlignment() {}
};
} // end namespace trailing_objects_internal
// Finally, the main type defined in this file, the one intended for users...
/// See the file comment for details on the usage of the
/// TrailingObjects type.
template <typename BaseTy, typename... TrailingTys>
class TrailingObjects : private trailing_objects_internal::TrailingObjectsImpl<
trailing_objects_internal::AlignmentCalcHelper<
TrailingTys...>::Alignment,
BaseTy, TrailingObjects<BaseTy, TrailingTys...>,
BaseTy, TrailingTys...> {
template <int A, typename B, typename T, typename P, typename... M>
friend class trailing_objects_internal::TrailingObjectsImpl;
template <typename... Tys> class Foo {};
typedef trailing_objects_internal::TrailingObjectsImpl<
trailing_objects_internal::AlignmentCalcHelper<TrailingTys...>::Alignment,
BaseTy, TrailingObjects<BaseTy, TrailingTys...>, BaseTy, TrailingTys...>
ParentType;
using TrailingObjectsBase = trailing_objects_internal::TrailingObjectsBase;
using ParentType::getTrailingObjectsImpl;
// This function contains only a static_assert BaseTy is final. The
// static_assert must be in a function, and not at class-level
// because BaseTy isn't complete at class instantiation time, but
// will be by the time this function is instantiated.
static void verifyTrailingObjectsAssertions() {
static_assert(std::is_final<BaseTy>(), "BaseTy must be final.");
}
// These two methods are the base of the recursion for this method.
static const BaseTy *
getTrailingObjectsImpl(const BaseTy *Obj,
TrailingObjectsBase::OverloadToken<BaseTy>) {
return Obj;
}
static BaseTy *
getTrailingObjectsImpl(BaseTy *Obj,
TrailingObjectsBase::OverloadToken<BaseTy>) {
return Obj;
}
// callNumTrailingObjects simply calls numTrailingObjects on the
// provided Obj -- except when the type being queried is BaseTy
// itself. There is always only one of the base object, so that case
// is handled here. (An additional benefit of indirecting through
// this function is that consumers only say "friend
// TrailingObjects", and thus, only this class itself can call the
// numTrailingObjects function.)
static size_t
callNumTrailingObjects(const BaseTy *Obj,
TrailingObjectsBase::OverloadToken<BaseTy>) {
return 1;
}
template <typename T>
static size_t callNumTrailingObjects(const BaseTy *Obj,
TrailingObjectsBase::OverloadToken<T>) {
return Obj->numTrailingObjects(TrailingObjectsBase::OverloadToken<T>());
}
public:
// Make this (privately inherited) member public.
#ifndef _MSC_VER
using ParentType::OverloadToken;
#else
// An MSVC bug prevents the above from working, (last tested at CL version
// 19.28). "Class5" in TrailingObjectsTest.cpp tests the problematic case.
template <typename T>
using OverloadToken = typename ParentType::template OverloadToken<T>;
#endif
/// Returns a pointer to the trailing object array of the given type
/// (which must be one of those specified in the class template). The
/// array may have zero or more elements in it.
template <typename T> const T *getTrailingObjects() const {
verifyTrailingObjectsAssertions();
// Forwards to an impl function with overloads, since member
// function templates can't be specialized.
return this->getTrailingObjectsImpl(
static_cast<const BaseTy *>(this),
TrailingObjectsBase::OverloadToken<T>());
}
/// Returns a pointer to the trailing object array of the given type
/// (which must be one of those specified in the class template). The
/// array may have zero or more elements in it.
template <typename T> T *getTrailingObjects() {
verifyTrailingObjectsAssertions();
// Forwards to an impl function with overloads, since member
// function templates can't be specialized.
return this->getTrailingObjectsImpl(
static_cast<BaseTy *>(this), TrailingObjectsBase::OverloadToken<T>());
}
/// Returns the size of the trailing data, if an object were
/// allocated with the given counts (The counts are in the same order
/// as the template arguments). This does not include the size of the
/// base object. The template arguments must be the same as those
/// used in the class; they are supplied here redundantly only so
/// that it's clear what the counts are counting in callers.
template <typename... Tys>
static constexpr std::enable_if_t<
std::is_same<Foo<TrailingTys...>, Foo<Tys...>>::value, size_t>
additionalSizeToAlloc(typename trailing_objects_internal::ExtractSecondType<
TrailingTys, size_t>::type... Counts) {
return ParentType::additionalSizeToAllocImpl(0, Counts...);
}
/// Returns the total size of an object if it were allocated with the
/// given trailing object counts. This is the same as
/// additionalSizeToAlloc, except it *does* include the size of the base
/// object.
template <typename... Tys>
static constexpr std::enable_if_t<
std::is_same<Foo<TrailingTys...>, Foo<Tys...>>::value, size_t>
totalSizeToAlloc(typename trailing_objects_internal::ExtractSecondType<
TrailingTys, size_t>::type... Counts) {
return sizeof(BaseTy) + ParentType::additionalSizeToAllocImpl(0, Counts...);
}
TrailingObjects() = default;
TrailingObjects(const TrailingObjects &) = delete;
TrailingObjects(TrailingObjects &&) = delete;
TrailingObjects &operator=(const TrailingObjects &) = delete;
TrailingObjects &operator=(TrailingObjects &&) = delete;
/// A type where its ::with_counts template member has a ::type member
/// suitable for use as uninitialized storage for an object with the given
/// trailing object counts. The template arguments are similar to those
/// of additionalSizeToAlloc.
///
/// Use with FixedSizeStorageOwner, e.g.:
///
/// \code{.cpp}
///
/// MyObj::FixedSizeStorage<void *>::with_counts<1u>::type myStackObjStorage;
/// MyObj::FixedSizeStorageOwner
/// myStackObjOwner(new ((void *)&myStackObjStorage) MyObj);
/// MyObj *const myStackObjPtr = myStackObjOwner.get();
///
/// \endcode
template <typename... Tys> struct FixedSizeStorage {
template <size_t... Counts> struct with_counts {
enum { Size = totalSizeToAlloc<Tys...>(Counts...) };
struct type {
alignas(BaseTy) char buffer[Size];
};
};
};
/// A type that acts as the owner for an object placed into fixed storage.
class FixedSizeStorageOwner {
public:
FixedSizeStorageOwner(BaseTy *p) : p(p) {}
~FixedSizeStorageOwner() {
assert(p && "FixedSizeStorageOwner owns null?");
p->~BaseTy();
}
BaseTy *get() { return p; }
const BaseTy *get() const { return p; }
private:
FixedSizeStorageOwner(const FixedSizeStorageOwner &) = delete;
FixedSizeStorageOwner(FixedSizeStorageOwner &&) = delete;
FixedSizeStorageOwner &operator=(const FixedSizeStorageOwner &) = delete;
FixedSizeStorageOwner &operator=(FixedSizeStorageOwner &&) = delete;
BaseTy *const p;
};
};
} // end namespace llvm
#endif