[eclipse-iceoryx#224] Document derive macro; add release notes

doc/release-notes/iceoryx2-unreleased.md

@@ -44,7 +44,7 @@
     * Introduce `IoxAtomic` that supports up to 128bit atomics on 32-bit architecture with a ReadWriteLock
     * add CI targets to officially support 32-bit
  * Example that demonstrates publish-subscribe communication with dynamic data [#205](https://github.com/eclipse-iceoryx/iceoryx2/issues/205)
-
+ * Introduce `PlacementNew` trait and derive proc-macro [#224](https://github.com/eclipse-iceoryx/iceoryx2/issues/224)
 
 ### Bugfixes
 

iceoryx2-bb/derive-macros/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "iceoryx2-bb-derive-macros"
+description = "iceoryx2: [internal] helper derive proc-macros"
 categories = { workspace = true }
-description = { workspace = true }
 edition = { workspace = true }
 homepage = { workspace = true }
 keywords = { workspace = true }

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

@@ -1,9 +1,48 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! Contains helper derive macros for iceoryx2.
+
 extern crate proc_macro;
 
 use proc_macro::TokenStream;
 use quote::quote;
 use syn::{parse_macro_input, Data, DeriveInput, Fields};
 
+/// Implements the [`iceoryx2_bb_elementary::placement_default::PlacementDefault`] trait when all
+/// fields of the struct implement it.
+///
+/// ```
+/// use iceoryx2_bb_derive_macros::PlacementDefault;
+/// use iceoryx2_bb_elementary::placement_default::PlacementDefault;
+/// use std::alloc::{alloc, dealloc, Layout};
+///
+/// #[derive(PlacementDefault)]
+/// struct MyLargeType {
+///     value_1: u64,
+///     value_2: Option<usize>,
+///     value_3: [u8; 10485760],
+/// }
+///
+/// let layout = Layout::new::<MyLargeType>();
+/// let raw_memory = unsafe { alloc(layout) } as *mut MyLargeType;
+/// unsafe { MyLargeType::placement_default(raw_memory) };
+///
+/// unsafe { &mut *raw_memory }.value_3[123] = 31;
+///
+/// unsafe { core::ptr::drop_in_place(raw_memory) };
+/// unsafe { dealloc(raw_memory.cast(), layout) };
+
+/// ```
 #[proc_macro_derive(PlacementDefault)]
 pub fn placement_default_derive(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -17,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);
-                        PlacementDefault::placement_default(field_address);
+                        iceoryx2_bb_elementary::placement_default::PlacementDefault::placement_default(field_address);
                     }
                 });
 
@@ -32,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);
-                        PlacementDefault::placement_default(field_address);
+                        iceoryx2_bb_elementary::placement_default::PlacementDefault::placement_default(field_address);
                     }
                 });
 

iceoryx2-bb/elementary/src/placement_default.rs

@@ -1,3 +1,18 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! Trait to perform placement new construction on a given pointer via [`Default::default()`].
+//! See [`PlacementDefault`] for example.
+
 use iceoryx2_pal_concurrency_sync::iox_atomic::*;
 
 /// A trait that allows types to perform a placement new based on their

iceoryx2-bb/elementary/src/pointer_trait.rs

@@ -10,6 +10,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! Trait which describes a form of pointer. Required to distinguish normal pointers from
+//! relocatable pointers.
+
 /// Trait which describes a form of pointer. Required to distinguish normal pointers from
 /// relocatable pointers.
 pub trait PointerTrait<T> {

iceoryx2-bb/elementary/src/relocatable_container.rs

@@ -10,6 +10,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! Describes a container which can shared between processes.
+
 use crate::{allocator::AllocationError, allocator::BaseAllocator};
 
 /// Describes a container which can shared between processes. Since the shared memory is often

iceoryx2-bb/trait-tests/tests/placement_new_tests.rs

@@ -1,3 +1,15 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
 #[cfg(test)]
 mod placement_new {
     use std::{

iceoryx2-pal/concurrency-sync/src/iox_atomic.rs

@@ -89,6 +89,7 @@ pub mod internal {
 
     pub trait AtomicInteger:
         Copy
+        + Default
         + Send
         + Eq
         + AddAssign
@@ -149,6 +150,7 @@ pub mod internal {
 /// iceoryx2 implementation of an atomic that has an internal [`RwLockWriterPreference`].
 /// It enables atomic operations on platforms that do not support them with the restriction that
 /// those operations are no longer lock-free.
+#[derive(Default)]
 #[repr(C)]
 pub struct IoxAtomic<T: internal::AtomicInteger> {
     data: UnsafeCell<T>,