From 90c4945e7cf41fb2bbbe24b8e2ae24f7bcef5584 Mon Sep 17 00:00:00 2001 From: Simon Hoinkis Date: Thu, 3 Mar 2022 14:45:53 +0100 Subject: [PATCH] iox-#1295 Fix typos, line length and rename 'Image' EventId to 'Objects' for Radar service Signed-off-by: Simon Hoinkis --- iceoryx_examples/icediscovery/README.md | 54 ++++++++++--------- .../include/discovery_blocking.hpp | 1 + .../icediscovery/iox_find_service.cpp | 4 +- .../icediscovery/iox_offer_service.cpp | 4 +- 4 files changed, 34 insertions(+), 29 deletions(-) diff --git a/iceoryx_examples/icediscovery/README.md b/iceoryx_examples/icediscovery/README.md index 651870bd6ae..4439f86bf98 100644 --- a/iceoryx_examples/icediscovery/README.md +++ b/iceoryx_examples/icediscovery/README.md @@ -47,7 +47,7 @@ It is included via: On that object we can call the method `findService` which expects the three service [string identifiers](../../doc/website/getting-started/overview.md#creating-service-descriptions-for-topics) and a callable which will be applied to all matching services. -In addition we have to specify whether we want to search for publishers (`MessagingPattern::PUB_SUB`) +In addition, we have to specify whether we want to search for publishers (`MessagingPattern::PUB_SUB`) used in publish-subscribe communication or servers (`MessagingPattern::REQ_RES`) used in request-response communication. @@ -68,7 +68,7 @@ We can search for exactly matching services: ```cpp serviceDiscovery.findService(iox::capro::IdString_t{"Radar"}, iox::capro::IdString_t{"FrontLeft"}, - iox::capro::IdString_t{"Image"}, + iox::capro::IdString_t{"Objects"}, printSearchResult, iox::popo::MessagingPattern::PUB_SUB); ``` @@ -93,7 +93,8 @@ their services, you should see sometimes 5 `Camera` services and sometimes none. Start the applications `iox-wait-for-service` and `iox-offer-service`. This can be done in any order, but for demonstration purposes `iox-offer-service` should be started last. -`iox-wait-for-service` uses a customized service discovery [Discovery](#implementation-of-discovery-with-blocking-wait) which supports to wait for services by including +`iox-wait-for-service` uses a customized service discovery [Discovery](#implementation-of-discovery-with-blocking-wait) +which supports to wait for services by including ```cpp @@ -121,7 +122,7 @@ auto query = [&]() { ``` This is essentially any callable with `bool(void)` signature, but it should depend on the discovery somehow (by capture), -as it is only checked when the service availability changes in some way. Here we require some specific service to be found +as it is only checked when the service availability changes in some way. Here, we require some specific service to be found before we proceed. @@ -137,11 +138,11 @@ Now we can wait until the service discovery changes and the service becomes avai bool serviceWasAvailable = discovery.waitUntil(query); ``` -This wait is blocking until the service was available. If it already is available we do not block and proceed. +This wait blocks until the service is available. If it already is available we do not block and proceed. It is important that due to the nature of concurrent systems we cannot know that the service is still available once we return from `waitUntil`, as the application offering the service may have stopped doing so in the meantime. -Usually we will assume that the service is available and may continue, e.g. by creating subscribers and running +Usually, we will assume that the service is available and may continue, e.g. by creating subscribers and running application specific code. We can also block until any unspecified change in the service availability occurs @@ -154,7 +155,7 @@ This change is relative to the last `findService` call we issued, i.e. if someth the available services at this point, we wake up and continue. We then can check any condition we like, but usually it will be most useful to again check discovery-related conditions. -Here we check whether a particular service becomes unavailable (essentially the negation of our query before) +Here, we check whether a particular service becomes unavailable (essentially the negation of our query before) ```cpp if (discovery.findService(service, instance, event).empty()) @@ -163,7 +164,7 @@ if (discovery.findService(service, instance, event).empty()) } ``` -Note that we use a customized `findService` version which returns a result container which can easily be build +Note that we use a customized `findService` version which returns a result container which can easily be built using the version which takes a function to be applied to all services in the search result. Once the service becomes unavailable, the application exits. @@ -180,13 +181,13 @@ if (discoveryPtr) ### Monitor service availability -If we want to continously monitor the availability of some service or check some discovery condition we can do so by +If we want to continuously monitor the availability of some service or check some discovery condition we can do so by using e.g. a listener to conditionally execute [callbacks](../callbacks). To do so, we start the applications `iox-discovery-monitor` and `iox-offer-service` (again in any order, but for demonstration purposes `iox-offer-service` should be started last). -Again we can use a [Discovery](#implementation-of-discovery-monitoring) customized for this purpose by including +Again, we can use a [Discovery](#implementation-of-discovery-monitoring) customized for this purpose by including ```cpp @@ -201,7 +202,7 @@ and creating it like so Discovery discovery; ``` -Afterwards we create a callback to be called whenever the service availability changes. +Afterwards, we create a callback to be called whenever the service availability changes. ```cpp @@ -222,7 +223,7 @@ auto callback = [&](Discovery& discovery) -> void { ``` This callback essentially checks whether a specific service is available or unavailable and generates output accordingly. -Other reactions are possible as well, such as changing the processing logic of an pplication. +Other reactions are possible as well, such as changing the processing logic of an application. To start the monitoring, we register the callback @@ -240,12 +241,12 @@ When we want to stop monitoring we have to deregister the callback discovery.deregisterCallback(); ``` -Here this is done at the very end where it is technically not required, but in a more complex application it could be done -while the application is processing data. The main processing loop of the application is deliberately left empty for simplicty. +Here, this is done at the very end where it is technically not required, but in a more complex application it could be done +while the application is processing data. The main processing loop of the application is deliberately left empty for simplicity. Usually it would interact with the callback by e.g. changing application behavior whenever the availability of some service changes. -While we only can attach one callback to the general event that the service availability changes in some way, we can generalize the mechanism -here to check for multiple conditions and react to each of them by e.g. calling a specific function. +While we only can attach one callback to the general event that the service availability changes in some way, we can +generalize the mechanism here to check for multiple conditions and react to each of them by e.g. calling a specific function. These conditions would still need to be checked in the callback we defined though. ### Implementation of Discovery with blocking wait @@ -263,7 +264,8 @@ ServiceDiscovery& serviceDiscovery() } ``` -This is useful as the `ServiceDiscovery` may be fairly large and in general there is no point in having multiple `ServiceDiscovery` objects that all have the same purpose and (if updated) same view of the available services. +This is useful as the `ServiceDiscovery` may be fairly large and in general there is no point in having multiple +`ServiceDiscovery` objects that all have the same purpose and (if updated) the same view of the available services. The key idea is to use a waitset and attach to the event that the service availability changes @@ -346,7 +348,8 @@ void Discovery::unblockWait() } ``` -This is can only be called once and makes all future wait calls non-blocking. It is useful to unblock any wait calls to be able to stop the application. +This can only be called once and makes all future wait calls non-blocking. It is useful to unblock any wait calls to be +able to stop the application. Finally we provide a custom implementation of `findService` which returns a container of our choice, in this case a `std::vector`. @@ -363,8 +366,8 @@ ServiceContainer Discovery::findService(const iox::cxx::optional [Check out icediscovery on GitHub :fontawesome-brands-github:](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icediscovery){ .md-button } diff --git a/iceoryx_examples/icediscovery/include/discovery_blocking.hpp b/iceoryx_examples/icediscovery/include/discovery_blocking.hpp index 906d24c1a16..5d621d8cbfa 100644 --- a/iceoryx_examples/icediscovery/include/discovery_blocking.hpp +++ b/iceoryx_examples/icediscovery/include/discovery_blocking.hpp @@ -51,6 +51,7 @@ class Discovery void unblockWait(); /// @brief get all services matching a findService query + /// @return ServiceContainer, containing the found services /// @note invokes findService of the native iceoryx ServiceDiscovery API ServiceContainer findService(const iox::cxx::optional& service, const iox::cxx::optional& instance, diff --git a/iceoryx_examples/icediscovery/iox_find_service.cpp b/iceoryx_examples/icediscovery/iox_find_service.cpp index 645110519fc..398d812625b 100644 --- a/iceoryx_examples/icediscovery/iox_find_service.cpp +++ b/iceoryx_examples/icediscovery/iox_find_service.cpp @@ -43,11 +43,11 @@ int main() { std::cout << "\n=========================================" << std::endl; - std::cout << "\nSearched for {'Radar', 'FrontLeft', 'Image'}. Found the following services:" << std::endl; + std::cout << "\nSearched for {'Radar', 'FrontLeft', 'Objects'}. Found the following services:" << std::endl; //! [search for unique service] serviceDiscovery.findService(iox::capro::IdString_t{"Radar"}, iox::capro::IdString_t{"FrontLeft"}, - iox::capro::IdString_t{"Image"}, + iox::capro::IdString_t{"Objects"}, printSearchResult, iox::popo::MessagingPattern::PUB_SUB); //! [search for unique service] diff --git a/iceoryx_examples/icediscovery/iox_offer_service.cpp b/iceoryx_examples/icediscovery/iox_offer_service.cpp index a027f5892f6..32b529bface 100644 --- a/iceoryx_examples/icediscovery/iox_offer_service.cpp +++ b/iceoryx_examples/icediscovery/iox_offer_service.cpp @@ -25,8 +25,8 @@ int main() iox::runtime::PoshRuntime::initRuntime(APP_NAME); // offer services by creating publishers - iox::popo::Publisher radarLeft({"Radar", "FrontLeft", "Image"}); - iox::popo::Publisher radarRight({"Radar", "FrontRight", "Image"}); + iox::popo::Publisher radarLeft({"Radar", "FrontLeft", "Objects"}); + iox::popo::Publisher radarRight({"Radar", "FrontRight", "Objects"}); iox::popo::Publisher lidarLeft({"Lidar", "FrontLeft", "Counter"}); iox::cxx::vector, 5> cameraPublishers;