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/lifetime.hpp>
#include <userver/compiler/impl/tls.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace compiler {
 
namespace impl {
 
bool AreCoroutineSwitchesAllowed() noexcept;
 
void IncrementLocalCoroutineSwitchBans() noexcept;
 
void DecrementLocalCoroutineSwitchBans() noexcept;
 
}  // namespace impl
 
/// @brief A scope that crashes if coroutine context switches are attempted.
///
/// This is useful to prevent accidental waiting operations in places where they would be disastrous,
/// e.g. while holding a thread-local resource.
///
/// The check only happens in debug builds.
class CoroutineSwitchBanScope {
public:
    CoroutineSwitchBanScope() noexcept;
 
    CoroutineSwitchBanScope(CoroutineSwitchBanScope&&) = delete;
    CoroutineSwitchBanScope& operator=(CoroutineSwitchBanScope&&) = delete;
    ~CoroutineSwitchBanScope();
};
 
/// @brief The scope that grants access to a thread-local variable.
///
/// @see compiler::ThreadLocal
template <typename VariableType>
class ThreadLocalScope final : private CoroutineSwitchBanScope {
public:
    ThreadLocalScope(ThreadLocalScope&&) = delete;
    ThreadLocalScope& operator=(ThreadLocalScope&&) = delete;
    ~ThreadLocalScope() = default;
 
    /// 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.
///
/// `ThreadLocal` should be passed a factory function that constructs the variable. Example usage:
///
/// @snippet compiler/thread_local_test.cpp  sample definition
/// @snippet compiler/thread_local_test.cpp  sample
///
/// An example with slightly more complex initialization for the variable:
///
/// @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 local_buffer = [] { return std::string{}; };
///
/// 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 local_buffer = [] { return std::string{}; };
///
/// 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>
class ThreadLocal final {
    static_assert(std::is_empty_v<Factory>);
    static_assert(std::is_same_v<VariableType, std::invoke_result_t<const Factory&>>);
 
public:
    consteval ThreadLocal()
        : factory_(Factory{})
    {}
 
    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.
    [[no_unique_address]] Factory factory_;
};
 
template <typename Factory>
ThreadLocal(Factory factory) -> ThreadLocal<std::invoke_result_t<const Factory&>, Factory>;
 
inline CoroutineSwitchBanScope::CoroutineSwitchBanScope() noexcept {
#ifndef NDEBUG
    impl::IncrementLocalCoroutineSwitchBans();
#endif
}
 
inline CoroutineSwitchBanScope::~CoroutineSwitchBanScope() {
#ifndef NDEBUG
    impl::DecrementLocalCoroutineSwitchBans();
#endif
}
 
template <typename VariableType>
ThreadLocalScope<VariableType>::ThreadLocalScope(VariableType& variable) noexcept : variable_(variable) {}
 
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