signal.h

Go to the documentation of this file.

/*
  This file is part of KDBindings.
 
  SPDX-FileCopyrightText: 2021 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
  Author: Sean Harmer <sean.harmer@kdab.com>
 
  SPDX-License-Identifier: MIT
 
  Contact KDAB at <info@kdab.com> for commercial licensing options.
*/
 
#pragma once
 
#include <assert.h>
#include <memory>
#include <stdexcept>
#include <type_traits>
#include <utility>
#include <forward_list>
 
#ifdef emit
static_assert(false, "KDBindings is not compatible with Qt's 'emit' keyword.\n"
                     "To use KDBindings with Qt, please define QT_NO_EMIT to disable Qt's 'emit' keyword.\n"
                     "If you're using CMake you can set KDBindings_QT_NO_EMIT to ON to add this.");
 
// Undefine emit to suppress more compiler errors after the static_assert failure.
// Otherwise the compiler would drown our custom error message with more errors.
#undef emit
#endif
 
#include <kdbindings/connection_evaluator.h>
#include <kdbindings/genindex_array.h>
#include <kdbindings/utils.h>
 
#include <kdbindings/KDBindingsConfig.h>
 
namespace KDBindings {
template<typename... Args>
class Signal
{
    static_assert(
            std::conjunction<std::negation<std::is_rvalue_reference<Args>>...>::value,
            "R-value references are not allowed as Signal parameters!");
 
    // The Signal::Impl class exists, so Signals can be implemented in a PIMPL-like way.
    // This allows us to easily move Signals without losing their ConnectionHandles, as well as
    // making an unconnected Signal only sizeof(shared_ptr).
    class Impl : public Private::SignalImplBase
    {
    public:
        Impl() noexcept { }
 
        ~Impl() noexcept { }
 
        // Signal::Impls are not copyable
        Impl(Impl const &other) = delete;
        Impl &operator=(Impl const &other) = delete;
 
        // Signal::Impls are not moveable, this would break the ConnectionHandles
        Impl(Impl &&other) = delete;
        Impl &operator=(Impl &&other) = delete;
 
        // Connects a std::function to the signal. The returned
        // value can be used to disconnect the function again.
        Private::GenerationalIndex connect(std::function<void(Args...)> const &slot)
        {
            Connection newConnection;
            newConnection.slot = slot;
            return m_connections.insert(std::move(newConnection));
        }
 
        // Establish a deferred connection between signal and slot, where ConnectionEvaluator object
        // is used to queue all the connection to evaluate later. The returned
        // value can be used to disconnect the slot later.
        Private::GenerationalIndex connectDeferred(const std::shared_ptr<ConnectionEvaluator> &evaluator, std::function<void(Args...)> const &slot)
        {
            auto weakEvaluator = std::weak_ptr<ConnectionEvaluator>(evaluator);
 
            auto deferredSlot = [weakEvaluator = std::move(weakEvaluator), slot](ConnectionHandle &handle, Args... args) {
                if (auto evaluatorPtr = weakEvaluator.lock()) {
                    auto lambda = [slot, args...]() {
                        slot(args...);
                    };
                    evaluatorPtr->enqueueSlotInvocation(handle, lambda);
                } else {
                    throw std::runtime_error("ConnectionEvaluator is no longer alive");
                }
            };
 
            Connection newConnection;
            newConnection.m_connectionEvaluator = evaluator;
            newConnection.slotReflective = deferredSlot;
 
            return m_connections.insert(std::move(newConnection));
        }
 
        Private::GenerationalIndex connectReflective(std::function<void(ConnectionHandle &handle, Args...)> const &slot)
        {
            Connection newConnection;
            newConnection.slotReflective = slot;
 
            return m_connections.insert(std::move(newConnection));
        }
 
        // Disconnects a previously connected function
        //
        // WARNING: While this function is marked with noexcept, it *may* terminate the program
        // if it is not possible to allocate memory or if mutex locking isn't possible.
        void disconnect(const ConnectionHandle &handle) noexcept override
        {
            // If the connection evaluator is still valid, remove any queued up slot invocations
            // associated with the given handle to prevent them from being evaluated in the future.
            auto idOpt = handle.m_id; // Retrieve the connection associated with this id
 
            // Proceed only if the id is valid
            if (idOpt.has_value()) {
                auto id = idOpt.value();
 
                // Retrieve the connection associated with this id
                auto connection = m_connections.get(id);
                if (connection && m_isEmitting) {
                    // We are currently still emitting the signal, so we need to defer the actual
                    // disconnect until the emit is done.
                    connection->toBeDisconnected = true;
                    m_disconnectedDuringEmit = true;
                    return;
                }
 
                if (connection && connection->m_connectionEvaluator.lock()) {
                    if (auto evaluatorPtr = connection->m_connectionEvaluator.lock()) {
                        evaluatorPtr->dequeueSlotInvocation(handle);
                    }
                }
 
                // Note: This function may throw if we're out of memory.
                // As `disconnect` is marked as `noexcept`, this will terminate the program.
                m_connections.erase(id);
            }
        }
 
        // Disconnects all previously connected functions
        //
        // WARNING: While this function is marked with noexcept, it *may* terminate the program
        // if it is not possible to allocate memory or if mutex locking isn't possible.
        void disconnectAll() noexcept
        {
            const auto numEntries = m_connections.entriesSize();
 
            const auto sharedThis = shared_from_this();
            for (auto i = decltype(numEntries){ 0 }; i < numEntries; ++i) {
                const auto indexOpt = m_connections.indexAtEntry(i);
                if (sharedThis && indexOpt) {
                    disconnect(ConnectionHandle(sharedThis, *indexOpt));
                }
            }
        }
 
        bool blockConnection(const Private::GenerationalIndex &id, bool blocked) override
        {
            Connection *connection = m_connections.get(id);
            if (connection) {
                const bool wasBlocked = connection->blocked;
                connection->blocked = blocked;
                return wasBlocked;
            } else {
                throw std::out_of_range("Provided ConnectionHandle does not match any connection\nLikely the connection was deleted before!");
            }
        }
 
        bool isConnectionActive(const Private::GenerationalIndex &id) const noexcept override
        {
            return m_connections.get(id);
        }
 
        bool isConnectionBlocked(const Private::GenerationalIndex &id) const override
        {
            auto connection = m_connections.get(id);
            if (connection) {
                return connection->blocked;
            } else {
                throw std::out_of_range("Provided ConnectionHandle does not match any connection\nLikely the connection was deleted before!");
            }
        }
 
        void emit(Args... p)
        {
            if (m_isEmitting) {
                throw std::runtime_error("Signal is already emitting, nested emits are not supported!");
            }
            m_isEmitting = true;
 
            const auto numEntries = m_connections.entriesSize();
 
            // This loop can *not* tolerate new connections being added to the signal inside a slot
            // Doing so will be undefined behavior
            for (auto i = decltype(numEntries){ 0 }; i < numEntries; ++i) {
                const auto index = m_connections.indexAtEntry(i);
 
                if (index) {
                    const auto con = m_connections.get(*index);
 
                    if (!con->blocked) {
                        if (con->slotReflective) {
                            if (auto sharedThis = shared_from_this(); sharedThis) {
                                ConnectionHandle handle(sharedThis, *index);
                                con->slotReflective(handle, p...);
                            }
                        } else if (con->slot) {
                            con->slot(p...);
                        }
                    }
                }
            }
            m_isEmitting = false;
 
            if (m_disconnectedDuringEmit) {
                m_disconnectedDuringEmit = false;
 
                // Because m_connections is using a GenerationIndexArray, this loop can tolerate
                // deletions inside the loop. So iterating over the array and deleting entries from it
                // should not lead to undefined behavior.
                for (auto i = decltype(numEntries){ 0 }; i < numEntries; ++i) {
                    const auto index = m_connections.indexAtEntry(i);
 
                    if (index.has_value()) {
                        const auto con = m_connections.get(index.value());
                        if (con->toBeDisconnected) {
                            disconnect(ConnectionHandle(shared_from_this(), index));
                        }
                    }
                }
            }
        }
 
    private:
        friend class Signal;
        struct Connection {
            std::function<void(Args...)> slot;
            std::function<void(ConnectionHandle &, Args...)> slotReflective;
            std::weak_ptr<ConnectionEvaluator> m_connectionEvaluator;
            bool blocked{ false };
            // When we disconnect while the signal is still emitting, we need to defer the actual disconnection
            // until the emit is done. This flag is set to true when the connection should be disconnected.
            bool toBeDisconnected{ false };
        };
 
        mutable Private::GenerationalIndexArray<Connection> m_connections;
 
        // If a reflective slot disconnects itself, we need to make sure to not deconstruct the std::function
        // while it is still running.
        // Therefore, defer all slot disconnections until the emit is done.
        //
        // Previously, we stored the ConnectionHandles that were to be disconnected in a list.
        // However, that would mean that disconnecting cannot be noexcept, as it may need to allocate memory in that list.
        // We can fix this by storing this information within each connection itself (the toBeDisconnected flag).
        // Because of the memory layout of the `struct Connection`, this shouldn't even use any more memory.
        //
        // The only downside is that we need to iterate over all connections to find the ones that need to be disconnected.
        // This is helped by using the m_disconnedDuringEmit flag to avoid unnecessary iterations.
        bool m_isEmitting = false;
        bool m_disconnectedDuringEmit = false;
    };
 
public:
    Signal() = default;
 
    Signal(const Signal &) = delete;
    Signal &operator=(Signal const &other) = delete;
 
    Signal(Signal &&other) noexcept = default;
    Signal &operator=(Signal &&other) noexcept = default;
 
    ~Signal() noexcept
    {
        disconnectAll();
    }
 
    KDBINDINGS_WARN_UNUSED ConnectionHandle connect(std::function<void(Args...)> const &slot)
    {
        ensureImpl();
 
        return ConnectionHandle{ m_impl, m_impl->connect(slot) };
    }
 
    KDBINDINGS_WARN_UNUSED ConnectionHandle connectReflective(std::function<void(ConnectionHandle &, Args...)> const &slot)
    {
        ensureImpl();
 
        return ConnectionHandle{ m_impl, m_impl->connectReflective(slot) };
    }
 
    KDBINDINGS_WARN_UNUSED ConnectionHandle connectSingleShot(std::function<void(Args...)> const &slot)
    {
        return connectReflective([slot](ConnectionHandle &handle, Args... args) {
            handle.disconnect();
            slot(args...);
        });
    }
 
    KDBINDINGS_WARN_UNUSED ConnectionHandle connectDeferred(const std::shared_ptr<ConnectionEvaluator> &evaluator, std::function<void(Args...)> const &slot)
    {
        ensureImpl();
 
        ConnectionHandle handle(m_impl, {});
        handle.setId(m_impl->connectDeferred(evaluator, slot));
        return handle;
    }
 
    // The enable_if_t makes sure that this connect function specialization is only
    // available if we provide a function that cannot be otherwise converted to a
    // std::function<void(Args...)>, as it otherwise tries to take precedence
    // over the normal connect function.
    template<typename Func, typename... FuncArgs, typename = std::enable_if_t<std::disjunction_v<std::negation<std::is_convertible<Func, std::function<void(Args...)>>>, std::integral_constant<bool, sizeof...(FuncArgs) /*Also enable this function if we want to bind at least one argument*/>>>>
    KDBINDINGS_WARN_UNUSED ConnectionHandle connect(Func &&slot, FuncArgs &&...args)
    {
        std::function<void(Args...)> bound = Private::bind_first(std::forward<Func>(slot), std::forward<FuncArgs>(args)...);
        return connect(bound);
    }
 
    void disconnect(const ConnectionHandle &handle)
    {
        if (m_impl && handle.belongsTo(*this) && handle.m_id.has_value()) {
            m_impl->disconnect(handle);
            // TODO check if Impl is now empty and reset
        } else {
            throw std::out_of_range("Provided ConnectionHandle does not match any connection\nLikely the connection was deleted before!");
        }
    }
 
    void disconnectAll() noexcept
    {
        if (m_impl) {
            m_impl->disconnectAll();
            // Once all connections are disconnected, we can release ownership of the Impl.
            // This does not destroy the Signal itself, just the Impl object.
            // If another slot is connected, another Impl object will be constructed.
            m_impl.reset();
        }
        // If m_impl is nullptr, we don't have any connections to disconnect
    }
 
    bool blockConnection(const ConnectionHandle &handle, bool blocked)
    {
        if (m_impl && handle.belongsTo(*this) && handle.m_id.has_value()) {
            return m_impl->blockConnection(*handle.m_id, blocked);
        } else {
            throw std::out_of_range("Provided ConnectionHandle does not match any connection\nLikely the connection was deleted before!");
        }
    }
 
    bool isConnectionBlocked(const ConnectionHandle &handle) const
    {
        assert(handle.belongsTo(*this));
        if (!m_impl) {
            throw std::out_of_range("Provided ConnectionHandle does not match any connection\nLikely the connection was deleted before!");
        }
 
        if (handle.m_id.has_value()) {
            return m_impl->isConnectionBlocked(*handle.m_id);
        } else {
            return false;
        }
    }
 
    void emit(Args... p) const
    {
        if (m_impl)
            m_impl->emit(p...);
 
        // if m_impl is nullptr, we don't have any slots connected, don't bother emitting
    }
 
private:
    friend class ConnectionHandle;
 
    void ensureImpl()
    {
        if (!m_impl) {
            m_impl = std::make_shared<Impl>();
        }
    }
 
    // shared_ptr is used here instead of unique_ptr, so ConnectionHandle instances can
    // use a weak_ptr to check if the Signal::Impl they reference is still alive.
    //
    // This makes Signals easily copyable in theory, but the semantics of this are unclear.
    // Copying could either simply copy the shared_ptr, which means the copy would share
    // the connections of the original, which is possibly unintuitive, or the Impl would
    // have to be copied as well.
    // This would however leave connections without handles to disconnect them.
    // So copying is forbidden for now.
    //
    // Think of this shared_ptr more like a unique_ptr with additional weak_ptr's
    // in ConnectionHandle that can check whether the Impl object is still alive.
    mutable std::shared_ptr<Impl> m_impl;
};
 
class ConnectionBlocker
{
public:
    explicit ConnectionBlocker(const ConnectionHandle &handle)
        : m_handle{ handle }
    {
        m_wasBlocked = m_handle.block(true);
    }
 
    ~ConnectionBlocker()
    {
        m_handle.block(m_wasBlocked);
    }
 
private:
    ConnectionHandle m_handle;
    bool m_wasBlocked{ false };
};
 
} // namespace KDBindings