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 ¤t(); 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. get(const Key<Type> & Key)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. getExisting(const Key<Type> & Key)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> derive(const Key<Type> & Key,typename std::decay<Type>::type Value)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 derive(const Key<Type> & Key,typename std::decay<Type>::type Value)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. derive(Type && Value)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 derive(Type && Value)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: TypedAnyStorage(T && Value)164 TypedAnyStorage(T &&Value) : Value(std::move(Value)) {} 165 getValuePtr()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: WithContext(Context C)189 WithContext(Context C) : Restore(Context::swapCurrent(std::move(C))) {} ~WithContext()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> WithContextValue(const Key<T> & K,typename std::decay<T>::type V)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> WithContextValue(T && V)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 221