feat: add support for proxy with no event loop thread

docs/using-sdbus-c++.md

@@ -411,19 +411,23 @@ On the **server** side, we generally need to create D-Bus objects and publish th
   * or in a non-blocking async way, through `enterEventLoopAsync()`,
   * or, when we have our own implementation of an event loop (e.g. we are using sd-event event loop), we can ask the connection for its underlying fd, I/O events and timeouts through `getEventLoopPollData()` and use that data in our event loop mechanism.
 
+The object takes the D-Bus connection as a reference in its constructor. This is the only way to wire connection and object together. We must make sure the connection exists as long as objects using it exist. 
+
 Of course, at any time before or after running the event loop on the connection, we can create and "hook", as well as remove, objects and proxies upon that connection.
 
 #### Using D-Bus connections on the client side
 
-On the **client** side we have more options when creating D-Bus proxies. That corresponds to three overloads of the `createProxy()` factory:
+On the **client** side we likewise need a connection -- just that unlike on the server side, we don't need to request a unique bus name on it. We have more options here when creating a proxy:
 
-  * In case we (the application) already maintain a D-Bus connection, e.g. because we a D-Bus service anyway, the simple and typical approach is to create proxy upon that connection. The proxy will share the connection with others. So we pass connection reference to proxy factory. With this approach we must of course ensure that the connection exists as long as the proxy exists.
+  * Pass an already existing connection as a reference. This is the typical approach when the application already maintains a D-Bus connection (maybe it provide D-Bus API on it, and/or it already has some proxies hooked on it). The proxy will share the connection with others. With this approach we must of course ensure that the connection exists as long as the proxy exists.
 
-  * Or -- and this is typical when we have a simple D-Bus client application -- we have another option: we let proxy maintain its own connection (and an associated thread):
+  * Or -- and this is typical when we have a simple D-Bus client application -- we have another option: we let the proxy maintain its own connection (and potentially an associated event loop thread, see below):
 
     * We either create the connection ourselves and `std::move` it to the proxy object factory. The proxy becomes an owner of this connection, and will run the event loop on that connection. This had the advantage that we may choose the type of connection (system, session, remote).
 
-    * Or we don't bother about any connection at all when creating a proxy (the factory overload with no connection parameter). Under the hood, the proxy creates its own *system bus* connection, creates a separate thread and runs an event loop in it. This is **the simplest approach** for non-complex D-Bus clients. For more complex ones, with big number of proxies, this hurts scalability but may improve concurrency (see discussion higher above), so we should make a conscious choice.
+    * Or we don't bother about any connection at all when creating a proxy (the factory overload with no connection parameter). Under the hood, the proxy creates its own *system bus* connection, creates a separate thread and runs an event loop in it. Quite **simple**, but as you can see, this hurts scalability in case of many proxies, as each would spawn and maintain its own event loop thread (see discussion higher above). But we don't necessarily need an event loop thread, in case our proxy doesn't need to listen to signals or async method call replies. Read on. 
+
+    It's also possible in this case to instruct the proxy to **not spawn an event loop thread** for its connection. There are many situations that we want to quickly create a proxy, carry out one or a few (synchronous) D-Bus calls, and let go of proxy. We call them light-weight proxies. For that purpose, spawning a new event loop thread comes with time and resource penalty, for nothing. To create such **a light-weight proxy**, use the factory/constructor overload with `dont_run_event_loop_thread_t`. All in above two bullet sub-points holds; the proxy just won't spawn a thread with an event loop in it. Note that such a proxy can be used only for synchronous D-Bus calls; it may not receive signals or async call replies. 
 
 #### Stopping I/O event loops graciously
 

include/sdbus-c++/IProxy.h

@@ -412,6 +412,11 @@ namespace sdbus {
         return PropertySetter(*this, propertyName);
     }
 
+    // Tag specifying that the proxy shall not run an event loop thread on its D-Bus connection.
+    // Such proxies are typically created to carry out a simple synchronous D-Bus call(s) and then are destroyed.
+    struct dont_run_event_loop_thread_t { explicit dont_run_event_loop_thread_t() = default; };
+    inline constexpr dont_run_event_loop_thread_t dont_run_event_loop_thread{};
+
     /*!
      * @brief Creates a proxy object for a specific remote D-Bus object
      *
@@ -458,6 +463,31 @@ namespace sdbus {
                                                             , std::string destination
                                                             , std::string objectPath );
 
+    /*!
+     * @brief Creates a proxy object for a specific remote D-Bus object
+     *
+     * @param[in] connection D-Bus connection to be used by the proxy object
+     * @param[in] destination Bus name that provides the remote D-Bus object
+     * @param[in] objectPath Path of the remote D-Bus object
+     * @param[in] dont_run_event_loop_thread tag to specify the behavior regarding running an event loop thread
+     * @return Pointer to the object proxy instance
+     *
+     * The provided connection will be used by the proxy to issue calls against the object.
+     * The Object proxy becomes an exclusive owner of this connection, but will not start an event loop
+     * thread on this connection. This is cheap construction and is suitable for short-lived proxies
+     * created just to execute simple synchronous D-Bus calls and then destroyed. Such blocking request-reply
+     * calls will work without an event loop (but signals, async calls, etc. won't).
+     *
+     * Code example:
+     * @code
+     * auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo", sdbus::dont_run_event_loop_thread);
+     * @endcode
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<sdbus::IConnection>&& connection
+                                                            , std::string destination
+                                                            , std::string objectPath
+                                                            , dont_run_event_loop_thread_t );
+
     /*!
      * @brief Creates a proxy object for a specific remote D-Bus object
      *
@@ -466,7 +496,7 @@ namespace sdbus {
      * @return Pointer to the object proxy instance
      *
      * No D-Bus connection is provided here, so the object proxy will create and manage
-     * his own connection, and will automatically start a procesing loop upon that connection
+     * his own connection, and will automatically start an event loop upon that connection
      * in a separate internal thread. Handlers for incoming signals and asynchronous
      * method replies will be executed in the context of that thread.
      *
@@ -478,6 +508,29 @@ namespace sdbus {
     [[nodiscard]] std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
                                                             , std::string objectPath );
 
+    /*!
+     * @brief Creates a proxy object for a specific remote D-Bus object
+     *
+     * @param[in] destination Bus name that provides the remote D-Bus object
+     * @param[in] objectPath Path of the remote D-Bus object
+     * @param[in] dont_run_event_loop_thread tag to specify the behavior regarding running an event loop thread
+     * @return Pointer to the object proxy instance
+     *
+     * No D-Bus connection is provided here, so the object proxy will create and manage
+     * his own connection, but it will not start an event loop thread. This is cheap
+     * construction and is suitable for short-lived proxies created just to execute simple
+     * synchronous D-Bus calls and then destroyed. Such blocking request-reply calls
+     * will work without an event loop (but signals, async calls, etc. won't).
+     *
+     * Code example:
+     * @code
+     * auto proxy = sdbus::createProxy("com.kistler.foo", "/com/kistler/foo", sdbus::dont_run_event_loop_thread );
+     * @endcode
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
+                                                            , std::string objectPath
+                                                            , dont_run_event_loop_thread_t );
+
 }
 
 #include <sdbus-c++/ConvenienceApiClasses.inl>

include/sdbus-c++/ProxyInterfaces.h

@@ -109,6 +109,22 @@ namespace sdbus {
         {
         }
 
+        /*!
+         * @brief Creates native-like proxy object instance
+         *
+         * @param[in] destination Bus name that provides a D-Bus object
+         * @param[in] objectPath Path of the D-Bus object
+         * @param[in] dont_run_event_loop_thread tag to specify the behavior regarding running an event loop thread
+         *
+         * This constructor overload creates a proxy that manages its own D-Bus connection(s).
+         * For more information on its behavior, consult @ref createProxy(std::string,std::string,sdbus::dont_run_event_loop_thread_t)
+         */
+        ProxyInterfaces(std::string destination, std::string objectPath, dont_run_event_loop_thread_t)
+            : ProxyObjectHolder(createProxy(std::move(destination), std::move(objectPath), dont_run_event_loop_thread))
+            , _Interfaces(getProxy())...
+        {
+        }
+
         /*!
          * @brief Creates native-like proxy object instance
          *
@@ -141,6 +157,23 @@ namespace sdbus {
         {
         }
 
+        /*!
+         * @brief Creates native-like proxy object instance
+         *
+         * @param[in] connection D-Bus connection to be used by the proxy object
+         * @param[in] destination Bus name that provides a D-Bus object
+         * @param[in] objectPath Path of the D-Bus object
+         * @param[in] dont_run_event_loop_thread tag to specify the behavior regarding running an event loop thread
+         *
+         * The proxy created this way becomes an owner of the connection.
+         * For more information on its behavior, consult @ref createProxy(std::unique_ptr<sdbus::IConnection>&&,std::string,std::string,sdbus::dont_run_event_loop_thread_t)
+         */
+        ProxyInterfaces(std::unique_ptr<sdbus::IConnection>&& connection, std::string destination, std::string objectPath, dont_run_event_loop_thread_t)
+                : ProxyObjectHolder(createProxy(std::move(connection), std::move(destination), std::move(objectPath), dont_run_event_loop_thread))
+                , _Interfaces(getProxy())...
+        {
+        }
+
         /*!
          * @brief Finishes proxy registration and makes the proxy ready for use
          *

src/Proxy.cpp

@@ -66,6 +66,21 @@ Proxy::Proxy( std::unique_ptr<sdbus::internal::IConnection>&& connection
     connection_->enterEventLoopAsync();
 }
 
+Proxy::Proxy( std::unique_ptr<sdbus::internal::IConnection>&& connection
+            , std::string destination
+            , std::string objectPath
+            , dont_run_event_loop_thread_t )
+    : connection_(std::move(connection))
+    , destination_(std::move(destination))
+    , objectPath_(std::move(objectPath))
+{
+    SDBUS_CHECK_SERVICE_NAME(destination_);
+    SDBUS_CHECK_OBJECT_PATH(objectPath_);
+
+    // Even though the connection is ours only, we don't start an event loop thread.
+    // This proxy is meant to be created, used for simple synchronous D-Bus call(s) and then dismissed.
+}
+
 MethodCall Proxy::createMethodCall(const std::string& interfaceName, const std::string& methodName)
 {
     return connection_->createMethodCall(destination_, objectPath_, interfaceName, methodName);
@@ -363,6 +378,22 @@ std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<IConnection>&& conne
                                                    , std::move(objectPath) );
 }
 
+std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<IConnection>&& connection
+                                          , std::string destination
+                                          , std::string objectPath
+                                          , dont_run_event_loop_thread_t )
+{
+    auto* sdbusConnection = dynamic_cast<sdbus::internal::IConnection*>(connection.get());
+    SDBUS_THROW_ERROR_IF(!sdbusConnection, "Connection is not a real sdbus-c++ connection", EINVAL);
+
+    connection.release();
+
+    return std::make_unique<sdbus::internal::Proxy>( std::unique_ptr<sdbus::internal::IConnection>(sdbusConnection)
+                                                   , std::move(destination)
+                                                   , std::move(objectPath)
+                                                   , dont_run_event_loop_thread );
+}
+
 std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
                                           , std::string objectPath )
 {
@@ -376,4 +407,19 @@ std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
                                                    , std::move(objectPath) );
 }
 
+std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
+                                          , std::string objectPath
+                                          , dont_run_event_loop_thread_t )
+{
+    auto connection = sdbus::createConnection();
+
+    auto sdbusConnection = std::unique_ptr<sdbus::internal::IConnection>(dynamic_cast<sdbus::internal::IConnection*>(connection.release()));
+    assert(sdbusConnection != nullptr);
+
+    return std::make_unique<sdbus::internal::Proxy>( std::move(sdbusConnection)
+                                                   , std::move(destination)
+                                                   , std::move(objectPath)
+                                                   , dont_run_event_loop_thread );
+}
+
 }

src/Proxy.h

@@ -50,6 +50,10 @@ namespace sdbus::internal {
         Proxy( std::unique_ptr<sdbus::internal::IConnection>&& connection
              , std::string destination
              , std::string objectPath );
+        Proxy( std::unique_ptr<sdbus::internal::IConnection>&& connection
+             , std::string destination
+             , std::string objectPath
+             , dont_run_event_loop_thread_t );
 
         MethodCall createMethodCall(const std::string& interfaceName, const std::string& methodName) override;
         MethodReply callMethod(const MethodCall& message, uint64_t timeout) override;

tests/integrationtests/DBusMethodsTests.cpp

@@ -272,3 +272,12 @@ TEST_F(SdbusTestObject, CannotSetGeneralMethodTimeoutWithLibsystemdVersionLessTh
     ASSERT_THROW(s_adaptorConnection->getMethodCallTimeout(), sdbus::Error);
 }
 #endif
+
+TEST_F(SdbusTestObject, CanCallMethodSynchronouslyWithoutAnEventLoopThread)
+{
+    auto proxy = std::make_unique<TestProxy>(BUS_NAME, OBJECT_PATH, sdbus::dont_run_event_loop_thread);
+
+    auto multiplyRes = proxy->multiply(INT64_VALUE, DOUBLE_VALUE);
+
+    ASSERT_THAT(multiplyRes, Eq(INT64_VALUE * DOUBLE_VALUE));
+}

tests/integrationtests/TestProxy.cpp

@@ -39,6 +39,13 @@ TestProxy::TestProxy(std::string destination, std::string objectPath)
     registerProxy();
 }
 
+TestProxy::TestProxy(std::string destination, std::string objectPath, dont_run_event_loop_thread_t)
+    : ProxyInterfaces(std::move(destination), std::move(objectPath), dont_run_event_loop_thread)
+{
+    // It doesn't make sense to register any signals here since proxy upon a D-Bus connection with no event loop thread
+    // will not receive any incoming messages except replies to synchronous D-Bus calls.
+}
+
 TestProxy::TestProxy(sdbus::IConnection& connection, std::string destination, std::string objectPath)
     : ProxyInterfaces(connection, std::move(destination), std::move(objectPath))
 {

tests/integrationtests/TestProxy.h

@@ -73,6 +73,7 @@ class TestProxy final : public sdbus::ProxyInterfaces< org::sdbuscpp::integratio
 {
 public:
     TestProxy(std::string destination, std::string objectPath);
+    TestProxy(std::string destination, std::string objectPath, dont_run_event_loop_thread_t);
     TestProxy(sdbus::IConnection& connection, std::string destination, std::string objectPath);
     ~TestProxy();