diff --git a/CMakeLists.txt b/CMakeLists.txt index 2762b20..016f584 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -133,7 +133,7 @@ endif() # DOCUMENTATION #---------------------------------- -option(BUILD_DOC "Build documentation" ON) +option(BUILD_DOC "Build doxygen documentation for sdbus-c++ API" ON) if(BUILD_DOC) add_subdirectory("${CMAKE_SOURCE_DIR}/doc") diff --git a/README.md b/README.md index 51556ac..3c6d2af 100644 --- a/README.md +++ b/README.md @@ -20,23 +20,27 @@ $ sudo make install * `BUILD_CODE_GEN` [boolean] - Option for building the stub code generator `sdbus-c++-xml2cpp` for generating the adaptor and proxy interfaces out of the D-Bus IDL XML description. `OFF` by default. Use `-DBUILD_CODE_GEN=ON` flag to turn on building the code gen. + Option for building the stub code generator `sdbus-c++-xml2cpp` for generating the adaptor and proxy interfaces out of the D-Bus IDL XML description. Default value: `OFF`. Use `-DBUILD_CODE_GEN=ON` flag to turn on building the code gen. + +* `BUILD_DOC` [boolean] + + Option for building Doxygen documentation of sdbus-c++ API. If `BUILD_DOC` is enabled, the documentation must still be built explicitly through `make doc`. Default value: `ON`. Use `-DBUILD_DOC=OFF` to disable searching for Doxygen and building Doxygen documentation of sdbus-c++ API. * `BUILD_TESTS` [boolean] - Option for building sdbus-c++ unit and integration tests, invokable by `make test`. That incorporates downloading and building static libraries of Google Test. `OFF` by default. Use `-DBUILD_TESTS=ON` to enable building the tests. With this option turned on, you may also enable/disable the following options: + Option for building sdbus-c++ unit and integration tests, invokable by `make test`. That incorporates downloading and building static libraries of Google Test. Default value: `OFF`. Use `-DBUILD_TESTS=ON` to enable building the tests. With this option turned on, you may also enable/disable the following options: * `BUILD_PERF_TESTS` [boolean] - Option for building sdbus-c++ performance tests. `OFF` by default. + Option for building sdbus-c++ performance tests. Default value: `OFF`. * `BUILD_STRESS_TESTS` [boolean] - Option for building sdbus-c++ stress tests. `OFF` by default. + Option for building sdbus-c++ stress tests. Default value: `OFF`. * `TESTS_INSTALL_PATH` [string] - Path where the test binaries shall get installed. Set to `/opt/test/bin` by default. + Path where the test binaries shall get installed. Default value: `/opt/test/bin`. Dependencies ------------ diff --git a/include/sdbus-c++/IConnection.h b/include/sdbus-c++/IConnection.h index de5d3a6..23a8497 100644 --- a/include/sdbus-c++/IConnection.h +++ b/include/sdbus-c++/IConnection.h @@ -38,8 +38,8 @@ namespace sdbus { * An interface to D-Bus bus connection. Incorporates implementation * of both synchronous and asynchronous processing loop. * - * All methods throw @sdbus::Error in case of failure. The class is - * thread-aware, but not thread-safe. + * All methods throw sdbus::Error in case of failure. All methods in + * this class are thread-aware, but not thread-safe. * ***********************************************/ class IConnection @@ -67,7 +67,7 @@ namespace sdbus { * @brief Enters the D-Bus processing loop * * The incoming D-Bus messages are processed in the loop. The method - * blocks indefinitely, until unblocked via @leaveProcessingLoop. + * blocks indefinitely, until unblocked via leaveProcessingLoop. * * @throws sdbus::Error in case of failure */ @@ -76,7 +76,7 @@ namespace sdbus { /*! * @brief Enters the D-Bus processing loop in a separate thread * - * The same as @enterProcessingLoop, except that it doesn't block + * The same as enterProcessingLoop, except that it doesn't block * because it runs the loop in a separate thread managed internally. */ virtual void enterProcessingLoopAsync() = 0; diff --git a/include/sdbus-c++/IObject.h b/include/sdbus-c++/IObject.h index ff18242..577e96b 100644 --- a/include/sdbus-c++/IObject.h +++ b/include/sdbus-c++/IObject.h @@ -47,8 +47,11 @@ namespace sdbus { * An interface to D-Bus object. Provides API for registration * of methods, signals, properties, and for emitting signals. * - * All methods throw @c sdbus::Error in case of failure. The class is - * thread-aware, but not thread-safe. + * All methods throw @c sdbus::Error in case of failure. + * In general, the class is thread-aware, but not thread-safe. + * However, the operation of creating and sending asynchronous + * method replies, as well as creating and emitting + * signals, is thread-safe. * ***********************************************/ class IObject @@ -62,7 +65,7 @@ namespace sdbus { * @param[in] inputSignature D-Bus signature of method input parameters * @param[in] outputSignature D-Bus signature of method output parameters * @param[in] methodCallback Callback that implements the body of the method - * @param[in] noReply If true, the method isn't expected to send reply + * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply) * * @throws sdbus::Error in case of failure */ @@ -81,7 +84,7 @@ namespace sdbus { * @param[in] inputSignature D-Bus signature of method input parameters * @param[in] outputSignature D-Bus signature of method output parameters * @param[in] asyncMethodCallback Callback that implements the body of the method - * @param[in] noReply If true, the method isn't expected to send reply + * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply) * * This overload register a method callback that will have a freedom to execute * its body in asynchronous contexts, and send the results from those contexts. @@ -103,6 +106,7 @@ namespace sdbus { * @param[in] interfaceName Name of an interface that the signal will fall under * @param[in] signalName Name of the signal * @param[in] signature D-Bus signature of signal parameters + * @param[in] flags D-Bus signal flags (deprecated) * * @throws sdbus::Error in case of failure */ @@ -118,6 +122,7 @@ namespace sdbus { * @param[in] propertyName Name of the property * @param[in] signature D-Bus signature of property parameters * @param[in] getCallback Callback that implements the body of the property getter + * @param[in] flags D-Bus property flags (deprecated, property update behavior) * * @throws sdbus::Error in case of failure */ @@ -135,6 +140,7 @@ namespace sdbus { * @param[in] signature D-Bus signature of property parameters * @param[in] getCallback Callback that implements the body of the property getter * @param[in] setCallback Callback that implements the body of the property setter + * @param[in] flags D-Bus property flags (deprecated, property update behavior) * * @throws sdbus::Error in case of failure */ @@ -327,6 +333,9 @@ namespace sdbus { * The provided connection will be used by the object to export methods, * issue signals and provide properties. * + * Creating a D-Bus object instance is (thread-)safe even upon the connection + * which is already running its processing loop. + * * Code example: * @code * auto proxy = sdbus::createObject(connection, "/com/kistler/foo"); diff --git a/include/sdbus-c++/IObjectProxy.h b/include/sdbus-c++/IObjectProxy.h index b6f8316..bc69a9c 100644 --- a/include/sdbus-c++/IObjectProxy.h +++ b/include/sdbus-c++/IObjectProxy.h @@ -47,8 +47,10 @@ namespace sdbus { * An interface to D-Bus object proxy. Provides API for calling * methods, getting/setting properties, and for registering to signals. * - * All methods throw @c sdbus::Error in case of failure. The class is - * thread-aware, but not thread-safe. + * All methods throw @c sdbus::Error in case of failure. + * In general, the class is thread-aware, but not thread-safe. + * However, the operation of creating and sending method calls + * (both synchronously and asynchronously) is thread-safe. * ***********************************************/ class IObjectProxy @@ -107,7 +109,7 @@ namespace sdbus { * @brief Calls method on the proxied D-Bus object asynchronously * * @param[in] message Message representing an async method call - * @param[in] asyncReplyHandler Handler for the async reply + * @param[in] asyncReplyCallback Handler for the async reply * * The call is non-blocking. It doesn't wait for the reply. Once the reply arrives, * the provided async reply handler will get invoked from the context of the connection @@ -284,11 +286,10 @@ namespace sdbus { * @return Pointer to the object proxy instance * * The provided connection will be used by the proxy to issue calls against the object, - * and signals, if any, will be subscribed to on this connection. Since the caller still - * remains the owner of the connection (the proxy just keeps reference to it) after the call, - * the proxy will not start its own background processing loop for incoming signals (if any), - * as it will rely on the client as an owner of the connection to handle processing of - * incoming messages on that connection by themselves. + * and signals, if any, will be subscribed to on this connection. The caller still + * remains the owner of the connection (the proxy just keeps a reference to it), and + * should make sure that a processing loop is running on that connection, so the proxy + * may receive incoming signals and asynchronous method replies. * * Code example: * @code @@ -308,11 +309,10 @@ namespace sdbus { * @return Pointer to the object proxy instance * * The provided connection will be used by the proxy to issue calls against the object, - * and signals, if any, will be subscribed to on this connection. Object proxy becomes - * an exclusive owner of this connection. The effect of this is that when there is at - * least one signal in proxy's interface, then the proxy will immediately start its own - * processing loop for this connection in a separate internal thread, causing incoming - * signals to be correctly received and processed in the context of that internal thread. + * and signals, if any, will be subscribed to on this connection. The Object proxy becomes + * an exclusive owner of this connection, and will automatically start a procesing 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. * * Code example: * @code @@ -330,14 +330,14 @@ namespace sdbus { * @param[in] objectPath Path of the D-Bus object * @return Pointer to the object proxy instance * - * This factory overload creates a proxy that manages its own D-Bus connection(s). - * When there is at least one signal in proxy's interface, then the proxy will immediately - * start its own processing loop for this connection in its own separate thread, causing - * incoming signals to be correctly received and processed in the context of that thread. + * 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 + * in a separate internal thread. Handlers for incoming signals and asynchronous + * method replies will be executed in the context of that thread. * * Code example: * @code - * auto proxy = sdbus::createObjectProxy(connection, "com.kistler.foo", "/com/kistler/foo"); + * auto proxy = sdbus::createObjectProxy("com.kistler.foo", "/com/kistler/foo"); * @endcode */ std::unique_ptr createObjectProxy( std::string destination