clang-tools-extra/clangd/support/Context.h

   1 //===--- Context.h - Mechanism for passing implicit data --------*- C++-*-===//
   2 //
   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
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // Context for storing and retrieving implicit data. Useful for passing implicit
  10 // parameters on a per-request basis.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_CONTEXT_H_
  15 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_CONTEXT_H_
  16
  17 #include "llvm/ADT/STLExtras.h"
  18 #include "llvm/Support/Compiler.h"
  19 #include <memory>
  20 #include <type_traits>
  21
  22 namespace clang {
  23 namespace clangd {
  24
  25 /// Values in a Context are indexed by typed keys.
  26 /// Key<T> serves two purposes:
  27 ///   - it provides a lookup key for the context (each Key is unique),
  28 ///   - it makes lookup type-safe: a Key<T> can only map to a T (or nothing).
  29 ///
  30 /// Example:
  31 ///    Key<int> RequestID;
  32 ///    Key<int> Version;
  33 ///
  34 ///    Context Ctx = Context::empty().derive(RequestID, 10).derive(Version, 3);
  35 ///    assert(*Ctx.get(RequestID) == 10);
  36 ///    assert(*Ctx.get(Version) == 3);
  37 ///
  38 /// Keys are typically used across multiple functions, so most of the time you
  39 /// would want to make them static class members or global variables.
  40 template <class Type> class Key {
  41 public:
  42   static_assert(!std::is_reference<Type>::value,
  43                 "Reference arguments to Key<> are not allowed");
  44
  45   constexpr Key() = default;
  46
  47   Key(Key const &) = delete;
  48   Key &operator=(Key const &) = delete;
  49   Key(Key &&) = delete;
  50   Key &operator=(Key &&) = delete;
  51 };
  52
  53 /// A context is an immutable container for per-request data that must be
  54 /// propagated through layers that don't care about it. An example is a request
  55 /// ID that we may want to use when logging.
  56 ///
  57 /// Conceptually, a context is a heterogeneous map<Key<T>, T>. Each key has
  58 /// an associated value type, which allows the map to be typesafe.
  59 ///
  60 /// There is an "ambient" context for each thread, Context::current().
  61 /// Most functions should read from this, and use WithContextValue or
  62 /// WithContext to extend or replace the context within a block scope.
  63 /// Only code dealing with threads and extension points should need to use
  64 /// other Context objects.
  65 ///
  66 /// You can't add data to an existing context, instead you create a new
  67 /// immutable context derived from it with extra data added. When you retrieve
  68 /// data, the context will walk up the parent chain until the key is found.
  69 class Context {
  70 public:
  71   /// Returns an empty root context that contains no data.
  72   static Context empty();
  73   /// Returns the context for the current thread, creating it if needed.
  74   static const Context &current();
  75   // Sets the current() context to Replacement, and returns the old context.
  76   // Prefer to use WithContext or WithContextValue to do this safely.
  77   static Context swapCurrent(Context Replacement);
  78
  79 private:
  80   struct Data;
  81   Context(std::shared_ptr<const Data> DataPtr);
  82
  83 public:
  84   /// Same as Context::empty(), please use Context::empty() instead.
  85   Context() = default;
  86
  87   /// Copy operations for this class are deleted, use an explicit clone() method
  88   /// when you need a copy of the context instead.
  89   Context(Context const &) = delete;
  90   Context &operator=(const Context &) = delete;
  91
  92   Context(Context &&) = default;
  93   Context &operator=(Context &&) = default;
  94
  95   /// Get data stored for a typed \p Key. If values are not found
  96   /// \returns Pointer to the data associated with \p Key. If no data is
  97   /// specified for \p Key, return null.
  98   template <class Type> const Type *get(const Key<Type> &Key) const {
  99     for (const Data *DataPtr = this->DataPtr.get(); DataPtr != nullptr;
 100          DataPtr = DataPtr->Parent.get()) {
 101       if (DataPtr->KeyPtr == &Key)
 102         return static_cast<const Type *>(DataPtr->Value->getValuePtr());
 103     }
 104     return nullptr;
 105   }
 106
 107   /// A helper to get a reference to a \p Key that must exist in the map.
 108   /// Must not be called for keys that are not in the map.
 109   template <class Type> const Type &getExisting(const Key<Type> &Key) const {
 110     auto Val = get(Key);
 111     assert(Val && "Key does not exist");
 112     return *Val;
 113   }
 114
 115   /// Derives a child context
 116   /// It is safe to move or destroy a parent context after calling derive().
 117   /// The child will keep its parent alive, and its data remains accessible.
 118   template <class Type>
 119   Context derive(const Key<Type> &Key,
 120                  typename std::decay<Type>::type Value) const & {
 121     return Context(std::make_shared<Data>(
 122         Data{/*Parent=*/DataPtr, &Key,
 123              std::make_unique<TypedAnyStorage<typename std::decay<Type>::type>>(
 124                  std::move(Value))}));
 125   }
 126
 127   template <class Type>
 128   Context
 129   derive(const Key<Type> &Key,
 130          typename std::decay<Type>::type Value) && /* takes ownership */ {
 131     return Context(std::make_shared<Data>(
 132         Data{/*Parent=*/std::move(DataPtr), &Key,
 133              std::make_unique<TypedAnyStorage<typename std::decay<Type>::type>>(
 134                  std::move(Value))}));
 135   }
 136
 137   /// Derives a child context, using an anonymous key.
 138   /// Intended for objects stored only for their destructor's side-effect.
 139   template <class Type> Context derive(Type &&Value) const & {
 140     static Key<typename std::decay<Type>::type> Private;
 141     return derive(Private, std::forward<Type>(Value));
 142   }
 143
 144   template <class Type> Context derive(Type &&Value) && {
 145     static Key<typename std::decay<Type>::type> Private;
 146     return std::move(*this).derive(Private, std::forward<Type>(Value));
 147   }
 148
 149   /// Clone this context object.
 150   Context clone() const;
 151
 152 private:
 153   class AnyStorage {
 154   public:
 155     virtual ~AnyStorage() = default;
 156     virtual void *getValuePtr() = 0;
 157   };
 158
 159   template <class T> class TypedAnyStorage : public Context::AnyStorage {
 160     static_assert(std::is_same<typename std::decay<T>::type, T>::value,
 161                   "Argument to TypedAnyStorage must be decayed");
 162
 163   public:
 164     TypedAnyStorage(T &&Value) : Value(std::move(Value)) {}
 165
 166     void *getValuePtr() override { return &Value; }
 167
 168   private:
 169     T Value;
 170   };
 171
 172   struct Data {
 173     // We need to make sure Parent outlives the Value, so the order of members
 174     // is important. We do that to allow classes stored in Context's child
 175     // layers to store references to the data in the parent layers.
 176     std::shared_ptr<const Data> Parent;
 177     const void *KeyPtr;
 178     std::unique_ptr<AnyStorage> Value;
 179   };
 180
 181   std::shared_ptr<const Data> DataPtr;
 182 };
 183
 184 /// WithContext replaces Context::current() with a provided scope.
 185 /// When the WithContext is destroyed, the original scope is restored.
 186 /// For extending the current context with new value, prefer WithContextValue.
 187 class LLVM_NODISCARD WithContext {
 188 public:
 189   WithContext(Context C) : Restore(Context::swapCurrent(std::move(C))) {}
 190   ~WithContext() { Context::swapCurrent(std::move(Restore)); }
 191   WithContext(const WithContext &) = delete;
 192   WithContext &operator=(const WithContext &) = delete;
 193   WithContext(WithContext &&) = delete;
 194   WithContext &operator=(WithContext &&) = delete;
 195
 196 private:
 197   Context Restore;
 198 };
 199
 200 /// WithContextValue extends Context::current() with a single value.
 201 /// When the WithContextValue is destroyed, the original scope is restored.
 202 class LLVM_NODISCARD WithContextValue {
 203 public:
 204   template <typename T>
 205   WithContextValue(const Key<T> &K, typename std::decay<T>::type V)
 206       : Restore(Context::current().derive(K, std::move(V))) {}
 207
 208   // Anonymous values can be used for the destructor side-effect.
 209   template <typename T>
 210   WithContextValue(T &&V)
 211       : Restore(Context::current().derive(std::forward<T>(V))) {}
 212
 213 private:
 214   WithContext Restore;
 215 };
 216
 217 } // namespace clangd
 218 } // namespace clang
 219
 220 #endif