[#224] Add documentation and example for PlacementDefault

Author: elfenpiff

FAQ.md

@@ -24,6 +24,14 @@ Use the feature flag `enforce_32bit_rwlock_atomic` which enforces 32-bit atomics
 targets at the cost of the lock-free guarantee. Meaning, when an application crashes at the wrong
 point in time it can lead to a system deadlock.
 
+## My Transmission Type Is Too Large, Encounter Stack Overflow On Initialization.
+
+Take a look at the
+[complex data types example](examples/rust/complex_data_types).
+
+In this example the `PlacementDefault` trait is introduced that allows in place initialization
+and solves the stack overflow issue when the data type is larger than the available stack size.
+
 ## Application does not remove services/ports on shutdown or several application restarts lead to port count exceeded
 
 The structs of iceoryx2 need to be able to cleanup all resources when they

examples/README.md

@@ -38,7 +38,7 @@ they interact and exchange data.
 
 | Name | Description |
 |------|-------------|
-| [complex data types](rust/complex_data_types) | Send zero-copy compatible versions of `Vec`, `String`, .... |
+| [complex data types](rust/complex_data_types) | Send zero-copy compatible versions of `Vec` and `String`. Introduces `PlacementDefault` trait for large data types to perform an in place initialization where otherwise a stack overflow would be encountered.|
 | [discovery](rust/discovery) | List all available services in a system. |
 | [docker](rust/docker) | Communicate between different docker containers and the host. |
 | [event](rust/event) | Exchanging event signals between multiple processes.|

examples/rust/complex_data_types/complex_data_types.rs

@@ -17,20 +17,24 @@ use iceoryx2_bb_container::{
     byte_string::FixedSizeByteString, queue::FixedSizeQueue, vec::FixedSizeVec,
 };
 
-#[derive(Debug, Default)]
+// For both data types we derive from PlacementDefault to allow in memory initialization
+// without any copy. Avoids stack overflows when data type is larger than the available stack.
+#[derive(Debug, Default, PlacementDefault)]
 #[repr(C)]
 pub struct ComplexData {
     name: FixedSizeByteString<4>,
     data: FixedSizeVec<u64, 4>,
 }
 
-#[derive(Debug, Default)]
+// For both data types we derive from PlacementDefault to allow in memory initialization
+// without any copy. Avoids stack overflows when data type is larger than the available stack.
+#[derive(Debug, Default, PlacementDefault)]
 #[repr(C)]
 pub struct ComplexDataType {
     plain_old_data: u64,
     text: FixedSizeByteString<8>,
     vec_of_data: FixedSizeVec<u64, 4>,
-    vec_of_complex_data: FixedSizeVec<ComplexData, 4>,
+    vec_of_complex_data: FixedSizeVec<ComplexData, 404857>,
     a_queue_of_things: FixedSizeQueue<FixedSizeByteString<4>, 2>,
 }
 
@@ -50,10 +54,15 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     let mut counter = 0;
 
     while let Iox2Event::Tick = Iox2::wait(CYCLE_TIME) {
-        // acquire and send out sample
-        let mut sample = publisher.loan()?;
-        let payload = sample.payload_mut();
+        // ComplexDataType as a size of over 30MB, we need to perform a placement new
+        // otherwise we will encounter a StackOverflow.
+        // Therefore, we acquire an uninitialized sample, use the PlacementDefault
+        // trait to initialize ComplexDataType in place and then populate it with data.
+        let mut sample = publisher.loan_uninit()?;
+        unsafe { ComplexDataType::placement_default(sample.payload_mut().as_mut_ptr()) };
+        let mut sample = unsafe { sample.assume_init() };
 
+        let payload = sample.payload_mut();
         payload.plain_old_data = counter;
         payload.text = FixedSizeByteString::from_bytes(b"hello")?;
         payload.vec_of_data.push(counter);

iceoryx2-bb/container/src/byte_string.rs

@@ -38,6 +38,7 @@ use std::{
 };
 
 use iceoryx2_bb_derive_macros::PlacementDefault;
+use iceoryx2_bb_elementary::placement_default::PlacementDefault;
 use iceoryx2_bb_log::{fail, fatal_panic};
 
 /// Returns the length of a string

iceoryx2-bb/container/src/semantic_string.rs

@@ -60,8 +60,6 @@
 //! }
 //! ```
 
-pub use iceoryx2_bb_elementary::placement_default::PlacementDefault;
-
 use crate::byte_string::FixedSizeByteStringModificationError;
 use crate::byte_string::{as_escaped_string, strnlen, FixedSizeByteString};
 use iceoryx2_bb_elementary::enum_gen;
@@ -381,10 +379,10 @@ macro_rules! semantic_string {
             value: iceoryx2_bb_container::byte_string::FixedSizeByteString<$capacity>
         }
 
-        impl iceoryx2_bb_container::semantic_string::PlacementDefault for $string_name {
+        impl iceoryx2_bb_elementary::placement_default::PlacementDefault for $string_name {
             unsafe fn placement_default(ptr: *mut Self) {
                 let ptr = core::ptr::addr_of_mut!((&mut *ptr).value);
-                iceoryx2_bb_container::semantic_string::PlacementDefault::placement_default(ptr)
+                iceoryx2_bb_elementary::placement_default::PlacementDefault::placement_default(ptr)
             }
         }
 

iceoryx2-bb/derive-macros/src/lib.rs

@@ -56,7 +56,7 @@ pub fn placement_default_derive(input: TokenStream) -> TokenStream {
                     let name = &f.ident;
                     quote! {
                         let field_address = core::ptr::addr_of_mut!((*ptr).#name);
-                        iceoryx2_bb_elementary::placement_default::PlacementDefault::placement_default(field_address);
+                        PlacementDefault::placement_default(field_address);
                     }
                 });
 
@@ -71,7 +71,7 @@ pub fn placement_default_derive(input: TokenStream) -> TokenStream {
                     let index = syn::Index::from(i);
                     quote! {
                         let field_address = core::ptr::addr_of_mut!((*ptr).#index);
-                        iceoryx2_bb_elementary::placement_default::PlacementDefault::placement_default(field_address);
+                        PlacementDefault::placement_default(field_address);
                     }
                 });
 
@@ -92,7 +92,7 @@ pub fn placement_default_derive(input: TokenStream) -> TokenStream {
     };
 
     let expanded = quote! {
-        impl #impl_generics iceoryx2_bb_elementary::placement_default::PlacementDefault for #name #ty_generics #where_clause {
+        impl #impl_generics PlacementDefault for #name #ty_generics #where_clause {
             #place_default_impl
         }
     };

iceoryx2-bb/system-types/Cargo.toml

@@ -14,6 +14,7 @@ version = { workspace = true }
 iceoryx2-bb-container = { workspace = true }
 iceoryx2-bb-log = { workspace = true }
 iceoryx2-pal-configuration = { workspace = true }
+iceoryx2-bb-elementary = { workspace = true }
 serde = { workspace = true }
 
 [dev-dependencies]

iceoryx2/Cargo.toml

@@ -22,6 +22,7 @@ enforce_32bit_rwlock_atomic = ["iceoryx2-pal-concurrency-sync/enforce_32bit_rwlo
 
 [dependencies]
 iceoryx2-bb-container = { workspace = true }
+iceoryx2-bb-derive-macros = { workspace = true }
 iceoryx2-bb-system-types = { workspace = true }
 iceoryx2-bb-lock-free = { workspace = true }
 iceoryx2-bb-log = { workspace = true }

iceoryx2/src/prelude.rs

@@ -17,4 +17,6 @@ pub use crate::service::{
     port_factory::publisher::UnableToDeliverStrategy, process_local, service_name::ServiceName,
     zero_copy, Service,
 };
+pub use iceoryx2_bb_derive_macros::PlacementDefault;
 pub use iceoryx2_bb_elementary::alignment::Alignment;
+pub use iceoryx2_bb_elementary::placement_default::PlacementDefault;