thread_local.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/compiler/thread_local.hpp
/// @brief Utilities for using thread-local variables in a coroutine-safe way
 
#include <type_traits>
 
#include <userver/compiler/impl/constexpr.hpp>
#include <userver/compiler/impl/lifetime.hpp>
#include <userver/compiler/impl/tls.hpp>
 
#if __cplusplus >= 202002L &&
    (__clang_major__ >= 13 || !defined(__clang__) && __GNUC__ >= 9)
// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
#define USERVER_IMPL_UNEVALUATED_LAMBDAS
#endif
 
USERVER_NAMESPACE_BEGIN
 
namespace compiler {
 
namespace impl {
 
bool AreCoroutineSwitchesAllowed() noexcept;
 
void IncrementLocalCoroutineSwitchBans() noexcept;
 
void DecrementLocalCoroutineSwitchBans() noexcept;
 
#ifdef USERVER_IMPL_UNEVALUATED_LAMBDAS
template <typename T, typename Factory = decltype([] { return T{}; })>
using UniqueDefaultFactory = Factory;
#else
template <typename T>
struct UniqueDefaultFactory final {
  static_assert(!sizeof(T),
                "Defaulted syntax for compiler::ThreadLocal is unavailable on "
                "your compiler. Please use the lambda-factory syntax, see the "
                "documentation for compiler::ThreadLocal.");
};
#endif
 
}  // namespace impl
 
/// @brief The scope that grants access to a thread-local variable.
///
/// @see compiler::ThreadLocal
template <typename VariableType>
class ThreadLocalScope final {
 public:
  ThreadLocalScope(ThreadLocalScope&&) = delete;
  ThreadLocalScope& operator=(ThreadLocalScope&&) = delete;
  ~ThreadLocalScope();
 
  /// Access the thread-local variable.
  VariableType& operator*() & noexcept USERVER_IMPL_LIFETIME_BOUND;
 
  /// Access the thread-local variable.
  VariableType* operator->() & noexcept USERVER_IMPL_LIFETIME_BOUND;
 
  /// @cond
  explicit ThreadLocalScope(VariableType& variable) noexcept;
 
  // Store ThreadLocalScope to a variable before using.
  VariableType& operator*() && noexcept = delete;
 
  // Store ThreadLocalScope to a variable before using.
  VariableType* operator->() && noexcept = delete;
  /// @endcond
 
 private:
  static_assert(!std::is_reference_v<VariableType>);
  static_assert(!std::is_const_v<VariableType>);
 
  VariableType& variable_;
};
 
/// @brief Creates a unique thread-local variable that can be used
/// in a coroutine-safe manner.
///
/// Thread-local variables are known to cause issues when used together
/// with userver coroutines:
///
/// * https://github.com/userver-framework/userver/issues/235
/// * https://github.com/userver-framework/userver/issues/242
///
/// Thread-local variables created through this class are protected against
/// these issues.
///
/// Example usage:
///
/// @snippet compiler/thread_local_test.cpp  sample definition
/// @snippet compiler/thread_local_test.cpp  sample
///
/// The thread-local variable is value-initialized.
///
/// In C++17 mode, or if you need to initialize the variable with some
/// arguments, the ThreadLocal should be passed a capture-less lambda that
/// constructs the variable. Example:
///
/// @snippet compiler/thread_local_test.cpp  sample factory
///
/// Once acquired through @a Use, the reference to the thread-local variable
/// should not be returned or otherwise escape the scope
/// of the ThreadLocalScope object. An example of buggy code:
///
/// @code
/// compiler::ThreadLocal<std::string> local_buffer;
///
/// std::string_view PrepareBuffer(std::string_view x, std::string_view y) {
///   const auto buffer = local_buffer.Use();
///   buffer->clear();
///   buffer->append(x);
///   buffer->append(y);
///   return *buffer;  // <- BUG! Reference to thread-local escapes the scope
/// }
/// @endcode
///
/// Do not store a reference to the thread-local object in a separate variable:
///
/// @code
/// compiler::ThreadLocal<std::string> local_buffer;
///
/// void WriteMessage(std::string_view x, std::string_view y) {
///   auto buffer_scope = local_buffer.Use();
///   // Code smell! This makes it more difficult to see that `buffer` is
///   // a reference to thread-local at a glance.
///   auto& buffer = *buffer_scope;
///   buffer.clear();
///   // ...
/// }
/// @endcode
///
/// Until the variable name goes out of scope, userver engine synchronization
/// primitives and clients (web or db) should not be used.
template <typename VariableType,
          typename Factory = impl::UniqueDefaultFactory<VariableType>>
class ThreadLocal final {
  static_assert(std::is_empty_v<Factory>);
  static_assert(
      std::is_same_v<VariableType, std::invoke_result_t<const Factory&>>);
 
 public:
  USERVER_IMPL_CONSTEVAL ThreadLocal() : factory_(Factory{}) {}
 
  USERVER_IMPL_CONSTEVAL /*implicit*/ ThreadLocal(Factory factory)
      : factory_(factory) {}
 
  ThreadLocalScope<VariableType> Use() {
    return ThreadLocalScope<VariableType>(impl::ThreadLocal(factory_));
  }
 
 private:
  // The ThreadLocal instance should have static storage duration. Still, if a
  // user defines it as a local variable or even a thread_local variable, it
  // should be harmless in practice, because ThreadLocal is an empty type,
  // mainly used to store the `FactoryFunc` template parameter.
  Factory factory_;
};
 
template <typename Factory>
ThreadLocal(Factory factory)
    -> ThreadLocal<std::invoke_result_t<const Factory&>, Factory>;
 
template <typename VariableType>
ThreadLocalScope<VariableType>::ThreadLocalScope(
    VariableType& variable) noexcept
    : variable_(variable) {
#ifndef NDEBUG
  impl::IncrementLocalCoroutineSwitchBans();
#endif
}
 
template <typename VariableType>
ThreadLocalScope<VariableType>::~ThreadLocalScope() {
#ifndef NDEBUG
  impl::DecrementLocalCoroutineSwitchBans();
#endif
}
 
template <typename VariableType>
VariableType& ThreadLocalScope<VariableType>::operator*() & noexcept  //
    USERVER_IMPL_LIFETIME_BOUND {
  return variable_;
}
 
template <typename VariableType>
VariableType* ThreadLocalScope<VariableType>::operator->() & noexcept  //
    USERVER_IMPL_LIFETIME_BOUND {
  return &**this;
}
 
}  // namespace compiler
 
USERVER_NAMESPACE_END