btcsignals.h

Go to the documentation of this file.

// Copyright (c) The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_UTIL_BTCSIGNALS_H
#define BITCOIN_UTIL_BTCSIGNALS_H
 
#include <sync.h>
 
#include <algorithm>
#include <atomic>
#include <functional>
#include <memory>
#include <optional>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace btcsignals {
 
class null_value
{
public:
    using result_type = void;
};
 
class any_of
{
public:
    // This is the only supported combiner with a non-void return type. As
    // such, its behavior is embedded into the signal functor.
    using result_type = bool;
};
 
template <typename Signature, typename Combiner = null_value>
class signal;
 
namespace detail {
#ifdef __cpp_lib_atomic_shared_ptr
template <typename T>
using atomic_shared_ptr = std::atomic<std::shared_ptr<T>>;
#else
template <typename T>
class atomic_shared_ptr
{
    std::shared_ptr<T> m_ptr;
 
public:
    explicit atomic_shared_ptr(std::shared_ptr<T> ptr) noexcept : m_ptr{std::move(ptr)} {}
    atomic_shared_ptr(const atomic_shared_ptr&) = delete;
    atomic_shared_ptr& operator=(const atomic_shared_ptr&) = delete;
    std::shared_ptr<T> load() const noexcept { return std::atomic_load(&m_ptr); }
    void store(std::shared_ptr<T> ptr) noexcept { std::atomic_store(&m_ptr, std::move(ptr)); }
};
#endif
} // namespace detail
 
/*
 * State object representing the liveness of a registered callback.
 * signal::connect() returns an enabled connection which can be held and
 * disabled in the future.
 */
class connection
{
    template <typename Signature, typename Combiner>
    friend class signal;
    class liveness
    {
        friend class connection;
 
        detail::atomic_shared_ptr<const void> m_callback;
 
        void disconnect() { m_callback.store(nullptr); }
 
    protected:
        explicit liveness(std::shared_ptr<const void> callback) : m_callback{std::move(callback)} {}
 
        std::shared_ptr<const void> load() const { return m_callback.load(); }
 
    public:
        bool connected() const { return load() != nullptr; }
    };
 
    std::shared_ptr<liveness> m_state{};
 
    explicit connection(std::shared_ptr<liveness>&& state) : m_state{std::move(state)}{}
 
public:
    constexpr connection() noexcept = default;
 
    void disconnect()
    {
        if (m_state) {
            m_state->disconnect();
        }
    }
 
    bool connected() const
    {
        return m_state && m_state->connected();
    }
};
 
/*
 * RAII-style connection management
 */
class scoped_connection
{
    connection m_conn;
 
public:
    explicit scoped_connection(connection rhs) noexcept : m_conn{std::move(rhs)} {}
 
    scoped_connection(scoped_connection&&) noexcept = default;
 
    scoped_connection& operator=(scoped_connection&&) = delete;
    scoped_connection& operator=(const scoped_connection&) = delete;
    scoped_connection(const scoped_connection&) = delete;
 
    void disconnect()
    {
        m_conn.disconnect();
    }
 
    ~scoped_connection()
    {
        disconnect();
    }
};
 
/*
 * Functor for calling zero or more connected callbacks
 */
template <typename Signature, typename Combiner>
class signal
{
    using function_type = std::function<Signature>;
 
    /*
     * Helper struct for maintaining a callback and its associated connection liveness
     */
    struct connection_holder : connection::liveness {
        template <typename Callable>
        explicit connection_holder(Callable&& callback)
            : liveness{std::make_shared<const function_type>(std::forward<Callable>(callback))}
        {
        }
 
        std::shared_ptr<const function_type> callback() const
        {
            return std::static_pointer_cast<const function_type>(load());
        }
    };
 
    mutable Mutex m_mutex;
 
    std::vector<std::shared_ptr<connection_holder>> m_connections GUARDED_BY(m_mutex){};
 
public:
    using result_type = Combiner::result_type;
 
    constexpr signal() noexcept = default;
    ~signal() = default;
 
    /*
     * For simplicity, disable all moving/copying/assigning.
     */
    signal(const signal&) = delete;
    signal(signal&&) = delete;
    signal& operator=(const signal&) = delete;
    signal& operator=(signal&&) = delete;
 
    /*
     * Execute all enabled callbacks for the signal. Rather than allowing for
     * custom combiners, the behavior of any_of is hard-coded here.
     *
     * Callbacks which return void require special handling.
     *
     * In order to avoid locking during the callbacks, the list of callbacks is
     * cached before they are called. This allows a callback to call connect(),
     * but the newly connected callback will not be run during the current
     * signal invocation.
     *
     * Note that the parameters are accepted as universal references, though
     * they are not perfectly forwarded as that could cause a use-after-move if
     * more than one callback is enabled.
     */
    template <typename... Args>
    [[nodiscard]] result_type operator()(Args&&... args) const EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
    {
        std::vector<std::shared_ptr<connection_holder>> connections;
        {
            LOCK(m_mutex);
            connections = m_connections;
        }
        if constexpr (std::is_void_v<result_type>) {
            static_assert(std::is_same_v<result_type, typename function_type::result_type>,
                          "Callback result type must be equal to the combiner result type (void).");
            for (const auto& connection : connections) {
                // Holding the callback pointer keeps the callback alive until
                // the call returns, even if it is disconnected concurrently.
                if (const auto callback{connection->callback()}) {
                    (*callback)(args...);
                }
            }
        } else {
            static_assert(std::is_same_v<Combiner, any_of>,
                          "only the any_of combiner is supported and hard-coded into this functor.");
            static_assert(std::is_same_v<result_type, typename function_type::result_type>,
                          "Callback result type must be equal to the combiner result type (bool).");
            result_type ret{false};
            for (const auto& connection : connections) {
                if (const auto callback{connection->callback()}) {
                    ret |= (*callback)(args...);
                }
            }
            return ret;
        }
    }
 
    /*
     * Connect a new callback to the signal. A forwarding callable accepts
     * anything that can be stored in a std::function.
     */
    template <typename Callable>
    connection connect(Callable&& func) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
    {
        LOCK(m_mutex);
 
        // Garbage-collect disconnected connections to prevent unbounded growth
        std::erase_if(m_connections, [](const auto& holder) { return !holder->connected(); });
 
        const auto& entry = m_connections.emplace_back(std::make_shared<connection_holder>(std::forward<Callable>(func)));
        return connection(entry);
    }
 
    /*
     * Returns true if there are no enabled callbacks
     */
    [[nodiscard]] bool empty() const EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
    {
        LOCK(m_mutex);
        return std::ranges::none_of(m_connections, [](const auto& holder) {
            return holder->connected();
        });
    }
};
 
} // namespace btcsignals
 
#endif // BITCOIN_UTIL_BTCSIGNALS_H