diff --git a/FAQ.md b/FAQ.md index 5c78dd8f9..337e1c67c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,19 @@ # Frequently Asked Questions +## Encountered a SEGFAULT. What Kind Of Data Types Can Be Transmitted Via iceoryx2 + +iceoryx2 stores all data in shared memory, which imposes certain restrictions. +Only data that is self-contained and does not use pointers to reference itself +is allowed. This is because shared memory is mapped at different offsets in +each process, rendering absolute pointers invalid. Additionally, if the data +structure uses the heap, it is stored locally within a process and cannot be +accessed by other processes. As a result, data types such as `String`, `Vec`, +or `HashMap` cannot be used as payload types. + +To address this, iceoryx2 provides shared-memory-compatible data types. You +can refer to the [complex data types example](examples/rust/complex_data_types), +which demonstrates the use of `FixedSizeByteString` and `FixedSizeVec`. + ## How To Send Data Where The Size Is Unknown At Compilation-Time? Take a look at the diff --git a/examples/README.md b/examples/README.md index a5daaa084..475332ae0 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,7 +1,8 @@ # Examples -> [!IMPORTANT] The examples are not yet functional in all languages. Check the -> list below to see what is already working! +> [!IMPORTANT] +> The examples are not yet functional in all languages. Check the list below to see +> what is already working! ## Foundations of Communication in iceoryx2 Applications @@ -40,6 +41,29 @@ intend. The service port factory allows you to fine-tune the settings and behavior of individual ports, giving you precise control over how they interact and exchange data. +## Payload Type Restrictions + +> [!CAUTION] +> iceoryx2 stores payload data in shared memory, which imposes the restriction that +> the payload type must be self-contained and cannot use heap memory. Additionally, +> internal pointers are not allowed because the shared memory is mapped at different +> offsets in each process, making absolute pointers invalid and potentially leading +> to segmentation faults. + +To address these limitations, we provide data types that are compatible with shared +memory. For Rust, we offer: + +* `FixedSizeByteString` +* `FixedSizeVec` + +For C++, we provide: + +* `iox::vector` +* `iox::string` +* `iox::list` + +These types are demonstrated in the complex data types example. + ## Overview | Name | Language | Description |