clang-tools  14.0.0git
Context.h
Go to the documentation of this file.
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>
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
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>
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
clang::clangd::WithContextValue::WithContextValue
WithContextValue(const Key< T > &K, typename std::decay< T >::type V)
Definition: Context.h:205
clang::clangd::Context::derive
Context derive(Type &&Value) const &
Derives a child context, using an anonymous key.
Definition: Context.h:139
Type
NodeType Type
Definition: HTMLGenerator.cpp:73
clang::clangd::Context::current
static const Context & current()
Returns the context for the current thread, creating it if needed.
Definition: Context.cpp:27
clang::clangd::Context::clone
Context clone() const
Clone this context object.
Definition: Context.cpp:20
clang::clangd::Context::get
const Type * get(const Key< Type > &Key) const
Get data stored for a typed Key.
Definition: Context.h:98
clang::clangd::WithContext::~WithContext
~WithContext()
Definition: Context.h:190
clang::clangd::Key::operator=
Key & operator=(Key const &)=delete
clang::clangd::WithContextValue
WithContextValue extends Context::current() with a single value.
Definition: Context.h:202
clang::clangd::Context::Context
Context()=default
Same as Context::empty(), please use Context::empty() instead.
clang::clangd::Key
Values in a Context are indexed by typed keys.
Definition: Context.h:40
clang::clangd::Context::swapCurrent
static Context swapCurrent(Context Replacement)
Definition: Context.cpp:29
clang::clangd::WithContextValue::WithContextValue
WithContextValue(T &&V)
Definition: Context.h:210
clang::clangd::WithContext
WithContext replaces Context::current() with a provided scope.
Definition: Context.h:187
clang::clangd::WithContext::WithContext
WithContext(Context C)
Definition: Context.h:189
Parent
const Node * Parent
Definition: ExtractFunction.cpp:152
clang::clangd::Context::operator=
Context & operator=(const Context &)=delete
clang::clangd::Context::derive
Context derive(const Key< Type > &Key, typename std::decay< Type >::type Value) const &
Derives a child context It is safe to move or destroy a parent context after calling derive().
Definition: Context.h:119
C
const Criteria C
Definition: FunctionCognitiveComplexityCheck.cpp:93
clang::clangd::Context::empty
static Context empty()
Returns an empty root context that contains no data.
Definition: Context.cpp:15
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::Context::derive
Context derive(Type &&Value) &&
Definition: Context.h:144
clang::clangd::Context::derive
Context derive(const Key< Type > &Key, typename std::decay< Type >::type Value) &&
Definition: Context.h:129
clang::clangd::Key::Key
constexpr Key()=default
clang::clangd::Context::getExisting
const Type & getExisting(const Key< Type > &Key) const
A helper to get a reference to a Key that must exist in the map.
Definition: Context.h:109
clang::clangd::Context
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition: Context.h:69
K
Kind K
Definition: Rename.cpp:442
Value
static constexpr bool Value
Definition: SuspiciousCallArgumentCheck.cpp:72