From 523855866507d004f76b909262650ec0a4dc72de Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Tue, 4 Jun 2024 13:40:19 +0200 Subject: [PATCH] [#224] Document derive macro; add release notes --- doc/release-notes/iceoryx2-unreleased.md | 2 +- iceoryx2-bb/derive-macros/Cargo.toml | 2 +- iceoryx2-bb/derive-macros/src/lib.rs | 43 ++++++++++++++++++- .../elementary/src/placement_default.rs | 15 +++++++ iceoryx2-bb/elementary/src/pointer_trait.rs | 3 ++ .../elementary/src/relocatable_container.rs | 2 + .../trait-tests/tests/placement_new_tests.rs | 12 ++++++ .../concurrency-sync/src/iox_atomic.rs | 2 + 8 files changed, 77 insertions(+), 4 deletions(-) diff --git a/doc/release-notes/iceoryx2-unreleased.md b/doc/release-notes/iceoryx2-unreleased.md index 693c877ff..5aa623f28 100644 --- a/doc/release-notes/iceoryx2-unreleased.md +++ b/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 diff --git a/iceoryx2-bb/derive-macros/Cargo.toml b/iceoryx2-bb/derive-macros/Cargo.toml index 114a45468..e247a0c92 100644 --- a/iceoryx2-bb/derive-macros/Cargo.toml +++ b/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 } diff --git a/iceoryx2-bb/derive-macros/src/lib.rs b/iceoryx2-bb/derive-macros/src/lib.rs index 6ffb799bc..805c2df6d 100644 --- a/iceoryx2-bb/derive-macros/src/lib.rs +++ b/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, +/// value_3: [u8; 10485760], +/// } +/// +/// let layout = Layout::new::(); +/// 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); } }); diff --git a/iceoryx2-bb/elementary/src/placement_default.rs b/iceoryx2-bb/elementary/src/placement_default.rs index c349afe2b..2ae4d0138 100644 --- a/iceoryx2-bb/elementary/src/placement_default.rs +++ b/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 diff --git a/iceoryx2-bb/elementary/src/pointer_trait.rs b/iceoryx2-bb/elementary/src/pointer_trait.rs index 24eb4190f..ba55c2335 100644 --- a/iceoryx2-bb/elementary/src/pointer_trait.rs +++ b/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 { diff --git a/iceoryx2-bb/elementary/src/relocatable_container.rs b/iceoryx2-bb/elementary/src/relocatable_container.rs index 545fdccde..d989683b3 100644 --- a/iceoryx2-bb/elementary/src/relocatable_container.rs +++ b/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 diff --git a/iceoryx2-bb/trait-tests/tests/placement_new_tests.rs b/iceoryx2-bb/trait-tests/tests/placement_new_tests.rs index 9ea1967be..1bbcb9937 100644 --- a/iceoryx2-bb/trait-tests/tests/placement_new_tests.rs +++ b/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::{ diff --git a/iceoryx2-pal/concurrency-sync/src/iox_atomic.rs b/iceoryx2-pal/concurrency-sync/src/iox_atomic.rs index 3c4312647..6816f9750 100644 --- a/iceoryx2-pal/concurrency-sync/src/iox_atomic.rs +++ b/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 { data: UnsafeCell,