Deferred connection evaluation

src/kdbindings/CMakeLists.txt

@@ -18,6 +18,7 @@ set(HEADERS
     property.h
     property_updater.h
     signal.h
+    connection_evaluator.h
     utils.h
 )
 

src/kdbindings/connection_evaluator.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <functional>
+#include <list>
+#include <mutex>
+
+namespace KDBindings {
+
+/**
+ * @brief Manages and evaluates deferred Signal connections.
+ *
+ * The ConnectionEvaluator class is responsible for managing and evaluating connections
+ * to Signals. It provides mechanisms to delay and control the evaluation of connections.
+ * It therefore allows controlling when and on which thread slots connected to a Signal are executed.
+ *
+ * @see Signal::connectDeferred()
+ */
+class ConnectionEvaluator
+{
+
+public:
+    ConnectionEvaluator() = default;
+
+    // ConnectionEvaluators are not copyable, 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;
+
+    // ConnectionEvaluators are not moveable, 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;
+
+    /**
+     * @brief Evaluate and execute deferred connections.
+     *
+     * This function is responsible for evaluating and executing deferred connections.
+     * And this function ensures thread safety
+     */
+    void evaluateDeferredConnections()
+    {
+        std::list<std::function<void()>> movedConnections;
+        {
+            std::lock_guard<std::mutex> lock(connectionsMutex);
+            movedConnections = std::move(connections);
+            // Reinitialize the connections list
+            connections = std::list<std::function<void()>>();
+        }
+
+        for (auto &connection : movedConnections) {
+            connection();
+        }
+    }
+
+private:
+    template<typename...>
+    friend class Signal;
+
+    void addConnection(std::function<void()> connection)
+    {
+        connections.push_back(connection);
+    }
+
+    std::list<std::function<void()>> connections;
+    std::mutex connectionsMutex;
+};
+} // namespace KDBindings

src/kdbindings/signal.h

@@ -18,7 +18,9 @@
 #include <stdexcept>
 #include <type_traits>
 #include <utility>
+#include <mutex>
 
+#include <kdbindings/connection_evaluator.h>
 #include <kdbindings/genindex_array.h>
 #include <kdbindings/utils.h>
 
@@ -204,6 +206,14 @@ class ConnectionHandle
  *
  * The Args type parameter pack describe which value types the Signal will emit.
  *
+ * Deferred Connection:
+ *
+ * KDBindings::Signal supports deferred connections, enabling the decoupling of signal
+ * emission from the execution of connected slots. With deferred connections, you can
+ * connect slots to the Signal that are not immediately executed when the signal is emitted.
+ * Instead, you can evaluate these deferred connections at a later time, allowing for
+ * asynchronous or delayed execution of connected slots.
+ * 
  * Examples:
  * - @ref 01-simple-connection/main.cpp
  * - @ref 02-signal-member/main.cpp
@@ -242,6 +252,27 @@ class Signal
             return m_connections.insert({ slot });
         }
 
+        // Establish a deferred connection between signal and slot, where ConnectionEvaluator object
+        // used to queue all the connection to evaluate later. The returned
+        // value can be used to disconnect the function again.
+        Private::GenerationalIndex connectDeferred(const std::shared_ptr<ConnectionEvaluator> &evaluator, std::function<void(Args...)> const &slot)
+        {
+            auto weakEvaluator = std::weak_ptr<ConnectionEvaluator>(evaluator);
+
+            auto connection = [weakEvaluator = std::move(weakEvaluator), slot](Args... args) {
+                // Check if the ConnectionEvaluator is still alive
+                if (auto evaluatorPtr = weakEvaluator.lock()) {
+                    auto lambda = [slot, args...]() {
+                        slot(args...);
+                    };
+                    evaluatorPtr->addConnection(lambda);
+                } else {
+                    throw std::runtime_error("ConnectionEvaluator is no longer alive");
+                }
+            };
+            return m_connections.insert({ connection, true });
+        }
+
         // Disconnects a previously connected function
         void disconnect(const Private::GenerationalIndex &id) override
         {
@@ -284,6 +315,7 @@ class Signal
         // Calls all connected functions
         void emit(Args... p) const
         {
+
             const auto numEntries = m_connections.entriesSize();
 
             // This loop can tolerate signal handles being disconnected inside a slot,
@@ -294,15 +326,17 @@ class Signal
                 if (index) {
                     const auto con = m_connections.get(*index);
 
-                    if (!con->blocked)
+                    if (!con->blocked) {
                         con->slot(p...);
+                    }
                 }
             }
         }
 
     private:
         struct Connection {
             std::function<void(Args...)> slot;
+            bool isDeferred{ false };
             bool blocked{ false };
         };
         mutable Private::GenerationalIndexArray<Connection> m_connections;
@@ -349,6 +383,29 @@ class Signal
         return ConnectionHandle{ m_impl, m_impl->connect(slot) };
     }
 
+    /**
+     * @brief Establishes a deferred connection between the provided evaluator and slot.
+     *
+     * This function allows connecting an evaluator and a slot such that the slot's execution
+     * is deferred until the conditions evaluated by the `evaluator` are met.
+     *
+     * First argument to the function is reference to a shared pointer to the `ConnectionEvaluator` responsible for determining
+     * when the slot should be executed.
+     * 
+     * @return An instance of ConnectionHandle, that can be used to disconnect
+     * or temporarily block the connection.
+     * 
+     * @note
+     * The `KDBindings::Signal` class itself is not thread-safe. While the `ConnectionEvaluator` is inherently
+     * thread-safe, ensure that any concurrent access to this Signal is protected externally to maintain thread safety.
+     */
+    ConnectionHandle connectDeferred(const std::shared_ptr<ConnectionEvaluator> &evaluator, std::function<void(Args...)> const &slot)
+    {
+        ensureImpl();
+
+        return ConnectionHandle(m_impl, m_impl->connectDeferred(evaluator, slot));
+    }
+
     /**
      * A template overload of Signal::connect that makes it easier to connect arbitrary functions to this
      * Signal.

tests/signal/tst_signal.cpp

@@ -11,9 +11,11 @@
 
 #include "kdbindings/utils.h"
 #include <kdbindings/signal.h>
+#include <kdbindings/connection_evaluator.h>
 
 #include <stdexcept>
 #include <string>
+#include <thread>
 
 #define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
 #include <doctest.h>
@@ -77,6 +79,138 @@ TEST_CASE("Signal connections")
         REQUIRE(lambdaCalled == true);
     }
 
+    SUBCASE("Disconnect Deferred Connection")
+    {
+        Signal<int> signal;
+        int val = 4;
+        auto evaluator = std::make_shared<ConnectionEvaluator>();
+
+        auto connection = signal.connectDeferred(evaluator, [&val](int value) {
+            val += value;
+        });
+
+        REQUIRE(connection.isActive());
+
+        signal.emit(4);
+        REQUIRE(val == 4); // val not changing immediately after emit 
+
+        connection.disconnect();
+        REQUIRE(!connection.isActive());
+
+        signal.emit(6); // It will not affect the result as the signal is disconnected
+        REQUIRE(val == 4);
+
+        evaluator->evaluateDeferredConnections();
+        REQUIRE(val == 8);
+    }
+
+    SUBCASE("Multiple Signals with Evaluator")
+    {
+        Signal<int> signal1;
+        Signal<int> signal2;
+        int val = 4;
+        auto evaluator = std::make_shared<ConnectionEvaluator>();
+
+        std::thread thread1([&] {
+            signal1.connectDeferred(evaluator, [&val](int value) {
+                val += value;
+            });
+        });
+
+        std::thread thread2([&] {
+            signal2.connectDeferred(evaluator, [&val](int value) {
+                val += value;
+            });
+        });
+
+        thread1.join();
+        thread2.join();
+
+        signal1.emit(2);
+        signal2.emit(3);
+        REQUIRE(val == 4); // val not changing immediately after emit 
+
+        evaluator->evaluateDeferredConnections();
+
+        REQUIRE(val == 9);
+    }
+
+    SUBCASE("Emit Multiple Signals with Evaluator")
+    {
+        Signal<int> signal1;
+        Signal<int> signal2;
+        int val1 = 4;
+        int val2 = 4;
+        auto evaluator = std::make_shared<ConnectionEvaluator>();
+
+        signal1.connectDeferred(evaluator, [&val1](int value) {
+            val1 += value;
+        });
+
+        signal2.connectDeferred(evaluator, [&val2](int value) {
+            val2 += value;
+        });
+
+        std::thread thread1([&] {
+            signal1.emit(2);
+        });
+
+        std::thread thread2([&] {
+            signal2.emit(3);
+        });
+
+        thread1.join();
+        thread2.join();
+
+        REQUIRE(val1 == 4);
+        REQUIRE(val2 == 4);
+
+        evaluator->evaluateDeferredConnections();
+
+        REQUIRE(val1 == 6);
+        REQUIRE(val2 == 7);
+    }
+
+    SUBCASE("Deferred Connect, Emit, Delete, and Evaluate")
+    {
+        Signal<int> signal;
+        int val = 4;
+        auto evaluator = std::make_shared<ConnectionEvaluator>();
+
+        auto connection = signal.connectDeferred(evaluator, [&val](int value) {
+            val += value;
+        });
+
+        REQUIRE(connection.isActive());
+
+        signal.emit(2);
+        REQUIRE(val == 4);
+
+        connection.disconnect();
+        evaluator->evaluateDeferredConnections();
+
+        REQUIRE(val == 6);
+    }
+
+    SUBCASE("Double Evaluate Deferred Connections")
+    {
+        Signal<int> signal;
+        int val = 4;
+        auto evaluator = std::make_shared<ConnectionEvaluator>();
+
+        signal.connectDeferred(evaluator, [&val](int value) {
+            val += value;
+        });
+
+        signal.emit(2);
+        REQUIRE(val == 4);
+
+        evaluator->evaluateDeferredConnections();
+        evaluator->evaluateDeferredConnections();
+
+        REQUIRE(val == 6);
+    }
+
     SUBCASE("A signal with arguments can be connected to a lambda and invoked with l-value args")
     {
         Signal<std::string, int> signal;