From 8b130f86521c7fd7b1bbdef1a4faa068519f30bc Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Thu, 5 Dec 2024 16:37:38 +0100 Subject: [PATCH] [#532] Update C++ readmes with a more detailed memory layout requirement description --- examples/cxx/domains/README.md | 14 ++++++++++++++ examples/cxx/event_based_communication/README.md | 14 ++++++++++++++ examples/cxx/publish_subscribe/README.md | 2 +- .../cxx/publish_subscribe_dynamic_data/README.md | 2 +- .../publish_subscribe_with_user_header/README.md | 2 +- 5 files changed, 31 insertions(+), 3 deletions(-) diff --git a/examples/cxx/domains/README.md b/examples/cxx/domains/README.md index 5dd9919d1..56bf64a66 100644 --- a/examples/cxx/domains/README.md +++ b/examples/cxx/domains/README.md @@ -31,6 +31,20 @@ not receive any data. ## Implementation +> [!CAUTION] +> Every payload you transmit with iceoryx2 must be compatible with shared +> memory. Specifically, it must: +> +> * be self contained, no heap, no pointers to external sources +> * have a uniform memory representation, ensuring that shared structs have the same data layout +> * not use pointers to manage their internal structure +> +> Data types like `std::string` or `std::vector` will cause undefined behavior +> and may result in segmentation faults. We provide alternative data types +> that are compatible with shared memory. See the +> [complex data type example](../complex_data_types) for guidance on how to +> use them. + To achieve this, we create a copy of the global configuration, modify the setting `config.global.prefix` using the user-provided CLI argument, and then set up the example accordingly. diff --git a/examples/cxx/event_based_communication/README.md b/examples/cxx/event_based_communication/README.md index 868c4151e..62d1b182f 100644 --- a/examples/cxx/event_based_communication/README.md +++ b/examples/cxx/event_based_communication/README.md @@ -2,6 +2,20 @@ ## Running The Example +> [!CAUTION] +> Every payload you transmit with iceoryx2 must be compatible with shared +> memory. Specifically, it must: +> +> * be self contained, no heap, no pointers to external sources +> * have a uniform memory representation, ensuring that shared structs have the same data layout +> * not use pointers to manage their internal structure +> +> Data types like `std::string` or `std::vector` will cause undefined behavior +> and may result in segmentation faults. We provide alternative data types +> that are compatible with shared memory. See the +> [complex data type example](../complex_data_types) for guidance on how to +> use them. + This example demonstrates iceoryx2's event multiplexing mechanism in a more complex setup. The iceoryx2 `Publisher` and `Subscriber` are integrated into custom `ExamplePublisher` and `ExampleSubscriber` classes, which also diff --git a/examples/cxx/publish_subscribe/README.md b/examples/cxx/publish_subscribe/README.md index de71f34a9..7ecea3d9c 100644 --- a/examples/cxx/publish_subscribe/README.md +++ b/examples/cxx/publish_subscribe/README.md @@ -10,7 +10,7 @@ instructions in the [C++ Examples Readme](../README.md). > memory. Specifically, it must: > > * be self contained, no heap, no pointers to external sources -> * have a uniform memory representation -> `#[repr(C)]` +> * have a uniform memory representation, ensuring that shared structs have the same data layout > * not use pointers to manage their internal structure > > Data types like `std::string` or `std::vector` will cause undefined behavior diff --git a/examples/cxx/publish_subscribe_dynamic_data/README.md b/examples/cxx/publish_subscribe_dynamic_data/README.md index 9e1a96fcd..cc63e3f47 100644 --- a/examples/cxx/publish_subscribe_dynamic_data/README.md +++ b/examples/cxx/publish_subscribe_dynamic_data/README.md @@ -12,7 +12,7 @@ allowing users to send samples of arbitrary sizes. > memory. Specifically, it must: > > * be self contained, no heap, no pointers to external sources -> * have a uniform memory representation -> `#[repr(C)]` +> * have a uniform memory representation, ensuring that shared structs have the same data layout > * not use pointers to manage their internal structure > > Data types like `std::string` or `std::vector` will cause undefined behavior diff --git a/examples/cxx/publish_subscribe_with_user_header/README.md b/examples/cxx/publish_subscribe_with_user_header/README.md index 5a64eecb4..49d99eb8e 100644 --- a/examples/cxx/publish_subscribe_with_user_header/README.md +++ b/examples/cxx/publish_subscribe_with_user_header/README.md @@ -10,7 +10,7 @@ instructions in the [C++ Examples Readme](../README.md). > memory. Specifically, it must: > > * be self contained, no heap, no pointers to external sources -> * have a uniform memory representation -> `#[repr(C)]` +> * have a uniform memory representation, ensuring that shared structs have the same data layout > * not use pointers to manage their internal structure > > Data types like `std::string` or `std::vector` will cause undefined behavior