From 72948c65fc890eaef83c25c34e441f81622b9cbe Mon Sep 17 00:00:00 2001 From: Simon Hoinkis Date: Thu, 15 Apr 2021 11:41:36 +0200 Subject: [PATCH] iox-#482 Further asciinema links Signed-off-by: Simon Hoinkis --- iceoryx_examples/callbacks_in_c/README.md | 2 +- .../ice_c_callbacks_with_context_data.c | 2 +- iceoryx_examples/icecrystal/Readme.md | 2 - iceoryx_examples/waitset/README.md | 37 +++++++++---------- iceoryx_examples/waitset_in_c/README.md | 15 ++++---- 5 files changed, 28 insertions(+), 30 deletions(-) diff --git a/iceoryx_examples/callbacks_in_c/README.md b/iceoryx_examples/callbacks_in_c/README.md index a3c6ed26c0..ea581b01ed 100644 --- a/iceoryx_examples/callbacks_in_c/README.md +++ b/iceoryx_examples/callbacks_in_c/README.md @@ -18,7 +18,7 @@ and at the Glossary of the ## Expected Output - +[![asciicast](https://asciinema.org/a/407369.svg)](https://asciinema.org/a/407369) ## Code Walkthrough diff --git a/iceoryx_examples/callbacks_in_c/ice_c_callbacks_with_context_data.c b/iceoryx_examples/callbacks_in_c/ice_c_callbacks_with_context_data.c index c4e133da77..da13f9f2f9 100644 --- a/iceoryx_examples/callbacks_in_c/ice_c_callbacks_with_context_data.c +++ b/iceoryx_examples/callbacks_in_c/ice_c_callbacks_with_context_data.c @@ -92,7 +92,7 @@ int main() signal(SIGINT, sigHandler); signal(SIGTERM, sigHandler); - iox_runtime_init("iox-c-callback-subscriber"); + iox_runtime_init("iox-c-callbacks-with-context-data"); // the listener starts a background thread and the callbacks of the attached events // will be called in this background thread when they are triggered diff --git a/iceoryx_examples/icecrystal/Readme.md b/iceoryx_examples/icecrystal/Readme.md index b77fac58c3..89d1be3bbe 100644 --- a/iceoryx_examples/icecrystal/Readme.md +++ b/iceoryx_examples/icecrystal/Readme.md @@ -2,8 +2,6 @@ ## Introduction -> This Readme.md is slightly outdated and not all functionality of the introspection is available with v1.0 - This example teaches you how to make use of the introspection for debugging purposes. With the introspection you can look into the machine room of RouDi. It shows live information about the memory usage and all registered processes. Additionally, it shows the publisher and subscriber ports that are created inside the shared diff --git a/iceoryx_examples/waitset/README.md b/iceoryx_examples/waitset/README.md index b02e73969e..a8a28341b5 100644 --- a/iceoryx_examples/waitset/README.md +++ b/iceoryx_examples/waitset/README.md @@ -1,4 +1,4 @@ -# WaitSet +q# WaitSet ## Thread Safety @@ -47,8 +47,7 @@ samples present in the subscriber. ## Expected Output - - +[![asciicast](https://asciinema.org/a/407372.svg)](https://asciinema.org/a/407372) ## Glossary @@ -150,9 +149,8 @@ send by `iox-cpp-waitset-publisher`. The publisher does not contain any _WaitSet logic and is explained in detail in the [icedelivery example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery). - - ### Basic + We create one subscriber and attach it to the WaitSet. Afterwards we wait for data in a loop and process it on arrival. To leave the loop and exit the application we have to register a signal handler that calls `waitset.markForDestruction()` @@ -192,9 +190,9 @@ waitset->attachState(subscriber, iox::popo::SubscriberState::HAS_DATA).or_else([ }); ``` -We create a loop which we will exit as soon as someone presses CTRL+c and our -signal handler sets shutdown to true. If this happens `markForDestruction` turns -the `waitset->wait()` into an empty non-blocking method and makes sure that we do +We create a loop which we will exit as soon as someone presses CTRL+c and our +signal handler sets shutdown to true. If this happens `markForDestruction` turns +the `waitset->wait()` into an empty non-blocking method and makes sure that we do not wait until infinity. ```cpp @@ -215,6 +213,7 @@ while (!shutdown.load()) } } ``` + Processing just one sample even if more might have arrived will cause `wait` to unblock again immediately to process the next sample (or shut down if requested). Due to the overhead of the `wait` call it may still be more efficient to process all samples in a loop until there are none left before waiting again, but it is not required. It would be required if we attach via `attachEvent` instead of `attachState`, since we might wake up due to the arrival of a second sample, only process the first and will not receive a wake up until a third sample arrives (which could be much later or never). ### Gateway @@ -222,8 +221,8 @@ Processing just one sample even if more might have arrived will cause `wait` to We have a list of subscribers which can be subscribed to any arbitrary topic and everytime we received a sample we would like to send the bytestream to a socket, write it into a file or print it to the console. But whatever we choose to do -we perform the same task for all the subscribers. And since we process all incoming -data right away we attach the `SubscriberEvent::DATA_RECEIVED` which notifies us +we perform the same task for all the subscribers. And since we process all incoming +data right away we attach the `SubscriberEvent::DATA_RECEIVED` which notifies us only once. Let's start by implementing our callback which prints the subscriber pointer, the @@ -232,7 +231,7 @@ as long as there are samples in the subscriber since we attached an event that n us only once. But it is impossible to miss samples since the notification is reset right after `wait` or `timedWait` is returned - this means if a sample arrives after those calls we will be notified again. -Additionally, we would like to count the sum of all processed samples therefor we +Additionally, we would like to count the sum of all processed samples therefor we add a second argument called `sumOfAllSamples`, the user defined context data. ```cpp @@ -250,16 +249,16 @@ void subscriberCallback(iox::popo::UntypedSubscriber* const subscriber, uint64_t } ``` -The _Event_ callback requires a signature of either `void (NotificationOrigin)` or -`void(NotificationOrigin, ContextDataType *)` when one would like to provide an additional +The _Event_ callback requires a signature of either `void (NotificationOrigin)` or +`void(NotificationOrigin, ContextDataType *)` when one would like to provide an additional data pointer to the callback. In our example the _NotificationOrigin_ is a `iox::popo::UntypedSubscriber` pointer which we use to acquire the latest sample by calling -`take()` and the `ContextDataType` is an `uint64_t` used to count the processed +`take()` and the `ContextDataType` is an `uint64_t` used to count the processed samples. When `take()` was successful we print our message to the console inside of the `and_then` lambda. -The `shutdownTrigger` uses a simpler callback which just informs us that we are +The `shutdownTrigger` uses a simpler callback which just informs us that we are exiting the program. Therefor we do not need an additional `ContextDataType` pointer. ```cpp void shutdownCallback(iox::popo::UserTrigger*) @@ -286,8 +285,8 @@ attach the subscribers to our _WaitSet_ with the `SubscriberEvent::DATA_RECEIVED Everytime one of the subscribers is receiving a new sample it will trigger the _WaitSet_. !!! attention - The user has to ensure that the contextData (`sumOfAllSamples`) in `attachEvent` - lives as long as the attachment, with its callback, is attached otherwise + The user has to ensure that the contextData (`sumOfAllSamples`) in `attachEvent` + lives as long as the attachment, with its callback, is attached otherwise the callback context data pointer is dangling. ```cpp @@ -308,7 +307,7 @@ for (auto i = 0; i < NUMBER_OF_SUBSCRIBERS; ++i) ``` `attachEvent` is returning a `cxx::expected` which informs us if attaching the event -succeeded. In the `.or_else([&](auto){/*...*/})` part we perform the error handling +succeeded. In the `.or_else([&](auto){/*...*/})` part we perform the error handling whenever `attachEvent` failed. Now our system is prepared and ready to work. We enter the event loop which @@ -346,7 +345,7 @@ while (true) In our next use case we would like to divide the subscribers into two groups and we do not want to attach a callback to them. Instead we perform the calls on the -subscribers directly. Additionally, we would like to be notified as long as there +subscribers directly. Additionally, we would like to be notified as long as there are samples in the subscriber queue therefore we have to attach the `SubscriberState::HAS_DATA`. We again start by creating a _WaitSet_ with a capacity of 5 (4 subscribers and 1 shutdownTrigger), diff --git a/iceoryx_examples/waitset_in_c/README.md b/iceoryx_examples/waitset_in_c/README.md index c331131430..a212777291 100644 --- a/iceoryx_examples/waitset_in_c/README.md +++ b/iceoryx_examples/waitset_in_c/README.md @@ -37,10 +37,11 @@ To run an example you need a running `iox-roudi` and the waitset publisher [icedelivery C example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery_in_c). ### Gateway + Let's say we would like to write a gateway and would like to forward every incoming message from a subscriber with the same callback. For instance we could perform -a memcopy of the received data into a specific struct. Additionally, we would -like to count all processed samples therefor we provide an extra void pointer +a memcopy of the received data into a specific struct. Additionally, we would +like to count all processed samples therefor we provide an extra void pointer argument called `contextData` which is a pointer to an `uint64_t`. This could be performed by a function that we attach to an event as a @@ -69,7 +70,7 @@ void subscriberCallback(iox_sub_t const subscriber, void * const contextData) } ``` -The `shutdownTrigger` gets a simplified callback where it just states that the +The `shutdownTrigger` gets a simplified callback where it just states that the program will be terminated. For this we do not need any context data. ```c void shutdownCallback(iox_user_trigger_t userTrigger) @@ -101,13 +102,13 @@ iox_ws_attach_user_trigger_event(waitSet, shutdownTrigger, 0U, shutdownCallback) In the next steps, we define `sumOfAllSamples`, create two subscribers with `iox_sub_init`, subscribe them to our topic and attach the event `SubscriberEvent_DATA_RECEIVED` to the WaitSet with -the `subscriberCallback`, an event id `1U` and a pointer to our user defined +the `subscriberCallback`, an event id `1U` and a pointer to our user defined context data `sumOfAllSamples` which is then provided as argument for the callback. !!! attention - The user has to ensure that the contextData (`sumOfAllSamples`) in - `iox_ws_attach_subscriber_event_with_context_data` lives as long as the - attachment, with its callback, is attached otherwise the callback context + The user has to ensure that the contextData (`sumOfAllSamples`) in + `iox_ws_attach_subscriber_event_with_context_data` lives as long as the + attachment, with its callback, is attached otherwise the callback context data pointer is dangling. ```c