feedc0de/sdbus-cpp
1
0
Fork 0
forked from Kistler-Group/sdbus-cpp
Code Pull Requests Activity

Provide better names to event loop-related IConnection methods

Browse Source
This commit is contained in:
sangelovic
2020-02-02 22:22:26 +01:00
parent dee6adce02
commit 3a4f343fb9
13 changed files with 128 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@@ -146,3 +146,4 @@ v0.8.0
v0.8.1
- Switch to full C++17 support
- Switch to more modern CMake (>=3.12)
- Provide better names to event loop-related IConnection methods, keep old ones marked as deprecated for backwards compatibility

24
docs/using-sdbus-c++.md
View File

@@ -135,7 +135,7 @@ The following diagram illustrates the major entities in sdbus-c++.
![class](sdbus-c++-class-diagram.png)
`IConnection` represents the concept of a D-Bus connection. You can connect to either the system bus or a session bus. Services can assign unique service names to those connections. A processing loop should be run on the connection.
`IConnection` represents the concept of a D-Bus connection. You can connect to either the system bus or a session bus. Services can assign unique service names to those connections. An I/O event loop should be run on the bus connection.
`IObject` represents the concept of an object that exposes its methods, signals and properties. Its responsibilities are:
@@ -262,8 +262,8 @@ int main(int argc, char *argv[])
concatenator->registerSignal(interfaceName, "concatenated", "s");
concatenator->finishRegistration();
// Run the loop on the connection.
connection->enterProcessingLoop();
// Run the I/O event loop on the bus connection.
connection->enterEventLoop();
}
```
@@ -363,14 +363,18 @@ We should bear that in mind when designing more complex, multi-threaded services
So, more technically, how can we use connections from the server and the client perspective?
#### Using D-Bus connections on the server side
On the **server** side, we generally need to create D-Bus objects and publish their APIs. For that we first need a connection with a unique bus name. We need to create the D-Bus connection manually ourselves, request bus name on it, and manually launch its event loop:
* either in a blocking way, through `enterProcessingLoop()`,
* or in a non-blocking async way, through `enterProcessingLoopAsync()`),
* 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 and use that fd in our loop.
* either in a blocking way, through `enterEventLoop()`,
* 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.
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:
* 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.
@@ -381,6 +385,10 @@ On the **client** side we have more options when creating D-Bus proxies. That co
* 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.
#### Stopping I/O event loops graciously
A connection with an asynchronous event loop (i.e. one initiated through `enterEventLoopAsync()`) will stop and join its event loop thread automatically in its destructor. An event loop that blocks in the synchronous `enterEventLoop()` call can be unblocked through `leaveEventLoop()` call on the respective bus connection issued from a different thread or from an OS signal handler.
Implementing the Concatenator example using convenience sdbus-c++ API layer
---------------------------------------------------------------------------
@@ -447,7 +455,7 @@ int main(int argc, char *argv[])
concatenator->finishRegistration();
// Run the loop on the connection.
connection->enterProcessingLoop();
connection->enterEventLoop();
}
```
@@ -729,7 +737,7 @@ int main(int argc, char *argv[])
Concatenator concatenator(*connection, objectPath);
// Run the loop on the connection.
connection->enterProcessingLoop();
connection->enterEventLoop();
}
```

91
include/sdbus-c++/IConnection.h
View File

@@ -38,7 +38,7 @@ namespace sdbus {
* @class IConnection
*
* An interface to D-Bus bus connection. Incorporates implementation
* of both synchronous and asynchronous processing loop.
* of both synchronous and asynchronous D-Bus I/O event loop.
*
* All methods throw sdbus::Error in case of failure. All methods in
* this class are thread-aware, but not thread-safe.
@@ -82,31 +82,31 @@ namespace sdbus {
virtual std::string getUniqueName() const = 0;
/*!
* @brief Enters the D-Bus processing loop
* @brief Enters I/O event loop on this bus connection
*
* The incoming D-Bus messages are processed in the loop. The method
* blocks indefinitely, until unblocked via leaveProcessingLoop.
* blocks indefinitely, until unblocked through leaveEventLoop().
*
* @throws sdbus::Error in case of failure
*/
virtual void enterProcessingLoop() = 0;
virtual void enterEventLoop() = 0;
/*!
* @brief Enters the D-Bus processing loop in a separate thread
* @brief Enters I/O event loop on this bus connection in a separate thread
*
* The same as enterProcessingLoop, except that it doesn't block
* because it runs the loop in a separate thread managed internally.
* The same as enterEventLoop, except that it doesn't block
* because it runs the loop in a separate, internally managed thread.
*/
virtual void enterProcessingLoopAsync() = 0;
virtual void enterEventLoopAsync() = 0;
/*!
* @brief Leaves the D-Bus processing loop
* @brief Leaves the I/O event loop running on this bus connection
*
* Ends the previously started processing loop.
* This causes the loop to exit and frees the thread serving the loop
*
* @throws sdbus::Error in case of failure
*/
virtual void leaveProcessingLoop() = 0;
virtual void leaveEventLoop() = 0;
/*!
* @brief Adds an ObjectManager at the specified D-Bus object path
@@ -120,7 +120,7 @@ namespace sdbus {
virtual void addObjectManager(const std::string& objectPath) = 0;
/*!
* @brief Returns parameters you can pass to poll
* @brief Returns fd, I/O events and timeout data you can pass to poll
*
* To integrate sdbus with your app's own custom event handling system
* (without the requirement of an extra thread), you can use this
@@ -130,26 +130,31 @@ namespace sdbus {
* to process the event. This means that all of sdbus's callbacks will
* arrive on your app's main event thread (opposed to on a thread created
* by sdbus-c++). If you are unsure what this all means then use
* enterProcessingLoop() or enterProcessingLoopAsync() instead.
* enterEventLoop() or enterEventLoopAsync() instead.
*
* To integrate sdbus-c++ into a gtk app, pass the file descriptor returned
* by this method to g_main_context_add_poll.
*
* @throws sdbus::Error in case of failure
*/
virtual PollData getProcessLoopPollData() const = 0;
virtual PollData getEventLoopPollData() const = 0;
/*!
* @brief Process a pending request
*
* @returns true if an event was processed, false if poll should be called
*
* Processes a single dbus event. All of sdbus-c++'s callbacks will be called
* from within this method. This method should ONLY be used in conjuction
* with getProcessLoopPollData(). enterProcessingLoop() and
* enterProcessingLoopAsync() will call this method for you, so there is no
* need to call it when using these. If you are unsure what this all means then
* don't use this method.
* with getEventLoopPollData().
* This method returns true if an I/O message was processed. This you can try
* to call this method again before going to poll on I/O events. The method
* returns false if no operations were pending, and the caller should then
* poll for I/O events before calling this method again.
* enterEventLoop() and enterEventLoopAsync() will call this method for you,
* so there is no need to call it when using these. If you are unsure what
* this all means then don't use this method.
*
* @returns true if an event was processed
* @throws sdbus::Error in case of failure
*/
virtual bool processPendingRequest() = 0;
@@ -184,6 +189,34 @@ namespace sdbus {
* @throws sdbus::Error in case of failure
*/
virtual uint64_t getMethodCallTimeout() const = 0;
/*!
* @copydoc IConnection::enterEventLoop()
*
* @deprecated This function has been replaced by enterEventLoop()
*/
[[deprecated("This function has been replaced by enterEventLoop()")]] void enterProcessingLoop();
/*!
* @copydoc IConnection::enterProcessingLoopAsync()
*
* @deprecated This function has been replaced by enterEventLoopAsync()
*/
[[deprecated("This function has been replaced by enterEventLoopAsync()")]] void enterProcessingLoopAsync();
/*!
* @copydoc IConnection::leaveProcessingLoop()
*
* @deprecated This function has been replaced by leaveEventLoop()
*/
[[deprecated("This function has been replaced by leaveEventLoop()")]] void leaveProcessingLoop();
/*!
* @copydoc IConnection::getProcessLoopPollData()
*
* @deprecated This function has been replaced by getEventLoopPollData()
*/
[[deprecated("This function has been replaced by getEventLoopPollData()")]] PollData getProcessLoopPollData() const;
};
template <typename _Rep, typename _Period>
@@ -193,6 +226,26 @@ namespace sdbus {
return setMethodCallTimeout(microsecs.count());
}
inline void IConnection::enterProcessingLoop()
{
enterEventLoop();
}
inline void IConnection::enterProcessingLoopAsync()
{
enterEventLoopAsync();
}
inline void IConnection::leaveProcessingLoop()
{
leaveEventLoop();
}
inline IConnection::PollData IConnection::getProcessLoopPollData() const
{
return getEventLoopPollData();
}
/*!
* @brief Creates/opens D-Bus system connection
*

2
include/sdbus-c++/IObject.h
View File

@@ -475,7 +475,7 @@ namespace sdbus {
* 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.
* which is already running its I/O event loop.
*
* Code example:
* @code

4
include/sdbus-c++/IProxy.h
View File

@@ -111,7 +111,7 @@ namespace sdbus {
*
* 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
* event loop processing thread.
* I/O event loop thread.
*
* Note: To avoid messing with messages, use higher-level API defined below.
*
@@ -315,7 +315,7 @@ namespace sdbus {
* 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. 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
* should make sure that an I/O event loop is running on that connection, so the proxy
* may receive incoming signals and asynchronous method replies.
*
* Code example:

26
src/Connection.cpp
View File

@@ -61,7 +61,7 @@ Connection::Connection(std::unique_ptr<ISdBus>&& interface, remote_system_bus_t,
Connection::~Connection()
{
leaveProcessingLoop();
Connection::leaveEventLoop();
}
void Connection::requestName(const std::string& name)
@@ -84,7 +84,7 @@ std::string Connection::getUniqueName() const
return unique;
}
void Connection::enterProcessingLoop()
void Connection::enterEventLoop()
{
loopThreadId_ = std::this_thread::get_id();
@@ -98,25 +98,25 @@ void Connection::enterProcessingLoop()
auto success = waitForNextRequest();
if (!success)
break; // Exit processing loop
break; // Exit I/O event loop
}
loopThreadId_ = std::thread::id{};
}
void Connection::enterProcessingLoopAsync()
void Connection::enterEventLoopAsync()
{
if (!asyncLoopThread_.joinable())
asyncLoopThread_ = std::thread([this](){ enterProcessingLoop(); });
asyncLoopThread_ = std::thread([this](){ enterEventLoop(); });
}
void Connection::leaveProcessingLoop()
void Connection::leaveEventLoop()
{
notifyProcessingLoopToExit();
joinWithProcessingLoop();
notifyEventLoopToExit();
joinWithEventLoop();
}
sdbus::IConnection::PollData Connection::getProcessLoopPollData() const
Connection::PollData Connection::getEventLoopPollData() const
{
ISdBus::PollData pollData;
auto r = iface_->sd_bus_get_poll_data(bus_.get(), &pollData);
@@ -358,13 +358,13 @@ void Connection::finishHandshake(sd_bus* bus)
SDBUS_THROW_ERROR_IF(r < 0, "Failed to flush bus on opening", -r);
}
void Connection::notifyProcessingLoopToExit()
void Connection::notifyEventLoopToExit()
{
assert(loopExitFd_.fd >= 0);
uint64_t value = 1;
auto r = write(loopExitFd_.fd, &value, sizeof(value));
SDBUS_THROW_ERROR_IF(r < 0, "Failed to notify processing loop", -errno);
SDBUS_THROW_ERROR_IF(r < 0, "Failed to notify event loop", -errno);
}
void Connection::clearExitNotification()
@@ -374,7 +374,7 @@ void Connection::clearExitNotification()
SDBUS_THROW_ERROR_IF(r < 0, "Failed to read from the event descriptor", -errno);
}
void Connection::joinWithProcessingLoop()
void Connection::joinWithEventLoop()
{
if (asyncLoopThread_.joinable())
asyncLoopThread_.join();
@@ -398,7 +398,7 @@ bool Connection::waitForNextRequest()
assert(bus != nullptr);
assert(loopExitFd_.fd != 0);
auto sdbusPollData = getProcessLoopPollData();
auto sdbusPollData = getEventLoopPollData();
struct pollfd fds[] = {{sdbusPollData.fd, sdbusPollData.events, 0}, {loopExitFd_.fd, POLLIN, 0}};
auto fdsCount = sizeof(fds)/sizeof(fds[0]);

14
src/Connection.h
View File

@@ -42,7 +42,7 @@
namespace sdbus::internal {
class Connection
class Connection final
: public sdbus::IConnection // External, public interface
, public sdbus::internal::IConnection // Internal, private interface
{
@@ -60,10 +60,10 @@ namespace sdbus::internal {
void requestName(const std::string& name) override;
void releaseName(const std::string& name) override;
std::string getUniqueName() const override;
void enterProcessingLoop() override;
void enterProcessingLoopAsync() override;
void leaveProcessingLoop() override;
sdbus::IConnection::PollData getProcessLoopPollData() const override;
void enterEventLoop() override;
void enterEventLoopAsync() override;
void leaveEventLoop() override;
PollData getEventLoopPollData() const override;
bool processPendingRequest() override;
void addObjectManager(const std::string& objectPath) override;
@@ -118,9 +118,9 @@ namespace sdbus::internal {
static std::string composeSignalMatchFilter( const std::string& objectPath
, const std::string& interfaceName
, const std::string& signalName );
void notifyProcessingLoopToExit();
void notifyEventLoopToExit();
void clearExitNotification();
void joinWithProcessingLoop();
void joinWithEventLoop();
static std::vector</*const */char*> to_strv(const std::vector<std::string>& strings);
struct LoopExitEventFd

4
src/IConnection.h
View File

@@ -88,8 +88,8 @@ namespace sdbus::internal {
, sd_bus_message_handler_t callback
, void* userData ) = 0;
virtual void enterProcessingLoopAsync() = 0;
virtual void leaveProcessingLoop() = 0;
virtual void enterEventLoopAsync() = 0;
virtual void leaveEventLoop() = 0;
virtual MethodReply tryCallMethodSynchronously(const MethodCall& message, uint64_t timeout) = 0;
};

2
src/Proxy.cpp
View File

@@ -56,7 +56,7 @@ Proxy::Proxy( std::unique_ptr<sdbus::internal::IConnection>&& connection
{
// The connection is ours only, i.e. it's us who has to manage the event loop upon this connection,
// in order that we get and process signals, async call replies, and other messages from D-Bus.
connection_->enterProcessingLoopAsync();
connection_->enterEventLoopAsync();
}
MethodCall Proxy::createMethodCall(const std::string& interfaceName, const std::string& methodName)

4
tests/integrationtests/AdaptorAndProxy_test.cpp
View File

@@ -62,12 +62,12 @@ public:
static void SetUpTestCase()
{
s_connection->requestName(INTERFACE_NAME);
s_connection->enterProcessingLoopAsync();
s_connection->enterEventLoopAsync();
}
static void TearDownTestCase()
{
s_connection->leaveProcessingLoop();
s_connection->leaveEventLoop();
s_connection->releaseName(INTERFACE_NAME);
}

6
tests/integrationtests/Connection_test.cpp
View File

@@ -78,13 +78,13 @@ TEST(Connection, CannotReleaseNonrequestedName)
ASSERT_THROW(connection->releaseName("some.random.nonrequested.name"), sdbus::Error);
}
TEST(Connection, CanEnterAndLeaveProcessingLoop)
TEST(Connection, CanEnterAndLeaveEventLoop)
{
auto connection = sdbus::createConnection();
connection->requestName(INTERFACE_NAME);
std::thread t([&](){ connection->enterProcessingLoop(); });
connection->leaveProcessingLoop();
std::thread t([&](){ connection->enterEventLoop(); });
connection->leaveEventLoop();
t.join();

2
tests/perftests/server.cpp
View File

@@ -97,5 +97,5 @@ int main(int /*argc*/, char */*argv*/[])
const char* objectPath = "/org/sdbuscpp/perftests";
PerftestAdaptor server(*connection, objectPath);
connection->enterProcessingLoop();
connection->enterEventLoop();
}

14
tests/stresstests/sdbus-c++-stress-tests.cpp
View File

@@ -392,7 +392,7 @@ int main(int argc, char *argv[])
{
CelsiusThermometerAdaptor thermometer(con, CELSIUS_THERMOMETER_OBJECT_PATH);
service2ThreadReady = true;
con.enterProcessingLoop();
con.enterEventLoop();
});
auto service1Connection = sdbus::createSystemBusConnection(SERVICE_1_BUS_NAME);
@@ -402,7 +402,7 @@ int main(int argc, char *argv[])
ConcatenatorAdaptor concatenator(con, CONCATENATOR_OBJECT_PATH);
FahrenheitThermometerAdaptor thermometer(con, FAHRENHEIT_THERMOMETER_OBJECT_PATH, false);
service1ThreadReady = true;
con.enterProcessingLoop();
con.enterEventLoop();
});
// Wait for both services to export their D-Bus objects
@@ -480,8 +480,8 @@ int main(int argc, char *argv[])
// We could run the loop in a sync way, but we want it to run also when proxies are destroyed for better
// coverage of multi-threaded scenarios, so we run it async and use condition variable for exit notification
//con.enterProcessingLoop();
con.enterProcessingLoopAsync();
//con.enterEventLoop();
con.enterEventLoopAsync();
std::unique_lock<std::mutex> lock(clientThreadExitMutex);
clientThreadExitCond.wait(lock, [&]{return clientThreadExit;});
@@ -493,17 +493,17 @@ int main(int argc, char *argv[])
std::this_thread::sleep_for(std::chrono::milliseconds(loopDuration));
//clientConnection->leaveProcessingLoop();
//clientConnection->leaveEventLoop();
std::unique_lock<std::mutex> lock(clientThreadExitMutex);
clientThreadExit = true;
lock.unlock();
clientThreadExitCond.notify_one();
clientThread.join();
service1Connection->leaveProcessingLoop();
service1Connection->leaveEventLoop();
service1Thread.join();
service2Connection->leaveProcessingLoop();
service2Connection->leaveEventLoop();
service2Thread.join();
}