connection_evaluator.h

Go to the documentation of this file.

/*
  This file is part of KDBindings.
 
  SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
  Author: Shivam Kunwar <shivam.kunwar@kdab.com>
 
  SPDX-License-Identifier: MIT
 
  Contact KDAB at <info@kdab.com> for commercial licensing options.
*/
#pragma once
 
#include <algorithm>
#include <functional>
#include <mutex>
 
#include <kdbindings/connection_handle.h>
 
namespace KDBindings {
 
class ConnectionEvaluator
{
 
public:
    ConnectionEvaluator() = default;
 
    // As it is designed to manage connections,
    // and copying it could lead to unexpected behavior, including duplication of connections and issues
    // related to connection lifetimes. Therefore, it is intentionally made non-copyable.
    ConnectionEvaluator(const ConnectionEvaluator &) noexcept = delete;
 
    ConnectionEvaluator &operator=(const ConnectionEvaluator &) noexcept = delete;
 
    // As they are captures by-reference
    // by the Signal, so moving them would lead to a dangling reference.
    ConnectionEvaluator(ConnectionEvaluator &&other) noexcept = delete;
 
    ConnectionEvaluator &operator=(ConnectionEvaluator &&other) noexcept = delete;
 
    virtual ~ConnectionEvaluator() = default;
 
    void evaluateDeferredConnections()
    {
        std::lock_guard<std::recursive_mutex> lock(m_slotInvocationMutex);
 
        if (m_isEvaluating) {
            // We're already evaluating, so we don't want to re-enter this function.
            return;
        }
        m_isEvaluating = true;
 
        // Current best-effort error handling will remove any further invocations that were queued.
        // We could use a queue and use a `while(!empty) { pop_front() }` loop instead to avoid this.
        // However, we would then ideally use a ring-buffer to avoid excessive allocations, which isn't in the STL.
        try {
            for (auto &pair : m_deferredSlotInvocations) {
                pair.second();
            }
        } catch (...) {
            // Best-effort: Reset the ConnectionEvaluator so that it at least doesn't execute the same erroneous slot multiple times.
            m_deferredSlotInvocations.clear();
            m_isEvaluating = false;
            throw;
        }
 
        m_deferredSlotInvocations.clear();
        m_isEvaluating = false;
    }
 
protected:
    virtual void onInvocationAdded() { }
 
private:
    template<typename...>
    friend class Signal;
 
    void enqueueSlotInvocation(const ConnectionHandle &handle, const std::function<void()> &slotInvocation)
    {
        {
            std::lock_guard<std::recursive_mutex> lock(m_slotInvocationMutex);
            m_deferredSlotInvocations.push_back({ handle, std::move(slotInvocation) });
        }
        onInvocationAdded();
    }
 
    // Note: This function is marked with noexcept but may theoretically encounter an exception and terminate the program if locking the mutex fails.
    // If this does happen though, there's likely something very wrong, so std::terminate is actually a reasonable way to handle this.
    //
    // In addition, we do need to use a recursive_mutex, as otherwise a slot from `enqueueSlotInvocation` may theoretically call this function and cause undefined behavior.
    void dequeueSlotInvocation(const ConnectionHandle &handle) noexcept
    {
        std::lock_guard<std::recursive_mutex> lock(m_slotInvocationMutex);
 
        if (m_isEvaluating) {
            // It's too late, we're already evaluating the deferred connections.
            // We can't remove the invocation now, as it might be currently evaluated.
            // And removing any invocations would be undefined behavior as we would invalidate
            // the loop indices in `evaluateDeferredConnections`.
            return;
        }
 
        auto handleMatches = [&handle](const auto &invocationPair) {
            return invocationPair.first == handle;
        };
 
        // Remove all invocations that match the handle
        m_deferredSlotInvocations.erase(
                std::remove_if(m_deferredSlotInvocations.begin(), m_deferredSlotInvocations.end(), handleMatches),
                m_deferredSlotInvocations.end());
    }
 
    std::vector<std::pair<ConnectionHandle, std::function<void()>>> m_deferredSlotInvocations;
    // We need to use a recursive mutex here, as `evaluateDeferredConnections` executes arbitrary user code.
    // This may end up in a call to dequeueSlotInvocation, which locks the same mutex.
    // We'll also need to add a flag to make sure we don't actually dequeue invocations while we're evaluating them.
    std::recursive_mutex m_slotInvocationMutex;
    bool m_isEvaluating = false;
};
} // namespace KDBindings