feat: add createLightWeightProxy overload for convenience (#474)

docs/using-sdbus-c++.md

@@ -466,18 +466,18 @@ On the **client** side we likewise need a connection -- just that unlike on the
 
   * 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. For discussion on options for running an event loop on that connection, see above section [Using D-Bus connections on the server side](#using-d-bus-connections-on-the-server-side).
 
-  * Or -- and this is a simpler approach for  simple D-Bus client applications -- we have another option: we let the proxy maintain its own connection (and potentially an associated event loop thread, see below). We have two options here:
+  * Or -- and this is a simpler approach for simple D-Bus client applications -- we have another option: we let the proxy maintain its own connection (and potentially an associated event loop thread, see below). We have two options here:
 
     * We either create the connection ourselves and `std::move` it to the proxy object factory. The proxy becomes an owner of this connection, and it will be his dedicated connection. This has the advantage that we may choose the type of connection (system, session, remote). Additionally,
 
       * when created **without** `dont_run_event_loop_thread_t` tag, the proxy **will start** a dedicated event loop thread on that connection;
       * or, when created **with** `dont_run_event_loop_thread_t` tag, the proxy will start **no** event loop thread on that connection.
 
-    * Or we don't care about connnections at all (proxy factory overloads with no connection parameter). Under the hood, the proxy creates its own connection, to either the session bus (when in a user context) or the system bus otherwise. Additionally:
+    * Or we don't care about connections at all (proxy factory overloads with no connection parameter). Under the hood, the proxy creates its own connection, to either the session bus (when in a user context) or the system bus otherwise. Additionally:
       * when created **without** `dont_run_event_loop_thread_t` tag, the proxy **will start** a dedicated event loop thread on that connection;
       * or, when created **with** `dont_run_event_loop_thread_t` tag, the proxy will start **no** event loop thread on that connection.
 
-    A proxy needs an event loop if it's a "**long-lived**" proxy that listens on incoming messages like signals, async call replies, atc. Sharing one connection with its one event loop is more scalable. Starting a dedicated event loop in a proxy is simpler from API perspective, but comes at a performance and resource cost for each proxy creation/destruction, and it hurts scalability. A simple and scalable option are "**short-lived, light-weight**" proxies. Quite a typical use case is that we occasionally need to carry out one or a few D-Bus calls and that's it. We may create a proxy, do the calls, and let go of proxy. Such a light-weight proxy is created when `dont_run_event_loop_thread_t` tag is passed to the proxy factory. Such a proxy **does not spawn** an event loop thread. It only support synchronous D-Bus calls (no signals, no async calls...), and is meant to be created, used right away, and then destroyed immediately.
+    A proxy needs an event loop if it's a "**long-lived**" proxy that listens on incoming messages like signals, async call replies, atc. Sharing one connection with its one event loop is more scalable. Starting a dedicated event loop in a proxy is simpler from API perspective, but comes at a performance and resource cost for each proxy creation/destruction, and it hurts scalability. A simple and scalable option are "**short-lived, light-weight**" proxies. Quite a typical use case is that we occasionally need to carry out one or a few D-Bus calls and that's it. We may create a proxy, do the calls, and let go of proxy. Such a light-weight proxy is created when `dont_run_event_loop_thread_t` tag is passed to the proxy factory (or with `createLightWeightProxy()`). Such a proxy **does not spawn** an event loop thread. It only support synchronous D-Bus calls (no signals, no async calls...), and is meant to be created, used right away, and then destroyed immediately.
 
 #### Stopping internal I/O event loops graciously
 

include/sdbus-c++/IProxy.h

@@ -385,7 +385,7 @@ namespace sdbus {
          * callMethod() function overload, which does not block the bus connection, or do the synchronous
          * call from another Proxy instance created just before the call and then destroyed (which is
          * anyway quite a typical approach in D-Bus implementations). Such proxy instance must have
-         * its own bus connection. So-called light-weight proxies (ones created with `dont_run_event_loop_thread`
+         * its own bus connection. So-called light-weight proxies (ones running without an event loop thread)
          * tag are designed for exactly that purpose.
          *
          * The default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().
@@ -416,7 +416,7 @@ namespace sdbus {
          * callMethod() function overload, which does not block the bus connection, or do the synchronous
          * call from another Proxy instance created just before the call and then destroyed (which is
          * anyway quite a typical approach in D-Bus implementations). Such proxy instance must have
-         * its own bus connection. So-called light-weight proxies (ones created with `dont_run_event_loop_thread`
+         * its own bus connection. So-called light-weight proxies (ones running without an event loop thread)
          * tag are designed for exactly that purpose.
          *
          * If timeout is zero, the default D-Bus method call timeout is used. See IConnection::getMethodCallTimeout().
@@ -889,7 +889,7 @@ namespace sdbus {
                                                             , ObjectPath objectPath );
 
     /*!
-     * @brief Creates a proxy object for a specific remote D-Bus object
+     * @brief Creates a light-weight 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
@@ -916,6 +916,15 @@ namespace sdbus {
                                                             , ObjectPath objectPath
                                                             , dont_run_event_loop_thread_t );
 
+    /*!
+     * @brief Creates a light-weight proxy object for a specific remote D-Bus object
+     *
+     * Does the same thing as createProxy(std::unique_ptr<sdbus::IConnection>&&, ServiceName, ObjectPath, dont_run_event_loop_thread_t);
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IProxy> createLightWeightProxy( std::unique_ptr<sdbus::IConnection>&& connection
+                                                                       , ServiceName destination
+                                                                       , ObjectPath objectPath );
+
     /*!
      * @brief Creates a proxy object for a specific remote D-Bus object
      *
@@ -937,7 +946,7 @@ namespace sdbus {
                                                             , ObjectPath objectPath );
 
     /*!
-     * @brief Creates a proxy object for a specific remote D-Bus object
+     * @brief Creates a light-weight 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
@@ -958,6 +967,13 @@ namespace sdbus {
                                                             , ObjectPath objectPath
                                                             , dont_run_event_loop_thread_t );
 
+    /*!
+     * @brief Creates a light-weight proxy object for a specific remote D-Bus object
+     *
+     * Does the same thing as createProxy(ServiceName, ObjectPath, dont_run_event_loop_thread_t);
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IProxy> createLightWeightProxy(ServiceName destination, ObjectPath objectPath);
+
 }
 
 #include <sdbus-c++/ConvenienceApiClasses.inl>

src/Proxy.cpp

@@ -400,6 +400,13 @@ std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<IConnection>&& conne
                                                    , dont_run_event_loop_thread );
 }
 
+std::unique_ptr<sdbus::IProxy> createLightWeightProxy( std::unique_ptr<IConnection>&& connection
+                                                     , ServiceName destination
+                                                     , ObjectPath objectPath )
+{
+    return createProxy(std::move(connection), std::move(destination), std::move(objectPath), dont_run_event_loop_thread);
+}
+
 std::unique_ptr<sdbus::IProxy> createProxy( ServiceName destination
                                           , ObjectPath objectPath )
 {
@@ -428,4 +435,9 @@ std::unique_ptr<sdbus::IProxy> createProxy( ServiceName destination
                                                    , dont_run_event_loop_thread );
 }
 
+std::unique_ptr<sdbus::IProxy> createLightWeightProxy(ServiceName destination, ObjectPath objectPath)
+{
+    return createProxy(std::move(destination), std::move(objectPath), dont_run_event_loop_thread);
+}
+
 }

tests/integrationtests/DBusMethodsTests.cpp

@@ -351,7 +351,7 @@ TYPED_TEST(SdbusTestObject, CanRegisterAdditionalVTableDynamicallyAtAnyTime)
                                       , sdbus::return_slot );
 
     // The new remote vtable is registered as long as we keep vtableSlot, so remote method calls now should pass
-    auto proxy = sdbus::createProxy(SERVICE_NAME, OBJECT_PATH, sdbus::dont_run_event_loop_thread);
+    auto proxy = sdbus::createLightWeightProxy(SERVICE_NAME, OBJECT_PATH);
     int result{};
     proxy->callMethod("subtract").onInterface(interfaceName).withArguments(10, 2).storeResultsTo(result);
 
@@ -370,6 +370,6 @@ TYPED_TEST(SdbusTestObject, CanUnregisterAdditionallyRegisteredVTableAtAnyTime)
     vtableSlot.reset(); // Letting the slot go means letting go the associated vtable registration
 
     // No such remote D-Bus method under given interface exists anymore...
-    auto proxy = sdbus::createProxy(SERVICE_NAME, OBJECT_PATH, sdbus::dont_run_event_loop_thread);
+    auto proxy = sdbus::createLightWeightProxy(SERVICE_NAME, OBJECT_PATH);
     ASSERT_THROW(proxy->callMethod("subtract").onInterface(interfaceName).withArguments(10, 2), sdbus::Error);
 }