iox-#64 Raw pointer API for publisher and subscriber

iceoryx-sys/src/chunk_header.rs

@@ -13,17 +13,21 @@ cpp! {{
 cpp_class!(pub unsafe struct ChunkHeader as "ChunkHeader");
 
 impl ChunkHeader {
-    pub fn from_user_payload<T>(payload: &T) -> Option<&Self> {
-        let payload = payload as *const T as *const c_void;
+    /// Get a reference to a ChunkHeader
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `payload` is non-null
+    pub(super) unsafe fn from_user_payload_unchecked<'a>(payload: *const c_void) -> &'a Self {
         unsafe {
             let chunk_header = cpp!([payload as "void*"] -> *const c_void as "const void*" {
                 return iox::mepoo::ChunkHeader::fromUserPayload(payload);
             });
-            if chunk_header.is_null() {
-                None
-            } else {
-                Some(&*(chunk_header as *const Self))
-            }
+            debug_assert!(
+                !chunk_header.is_null(),
+                "The ChunkHeader ptr should always be non-null when the payload ptr was non-null!"
+            );
+            &*(chunk_header as *const Self)
         }
     }
 

iceoryx-sys/src/lib.rs

@@ -25,6 +25,10 @@ pub use queue_policy::QueueFullPolicy;
 mod runtime;
 pub use runtime::Runtime;
 
+mod sample;
+pub use sample::RawSample;
+pub use sample::RawSampleMut;
+
 mod subscriber;
 pub use subscriber::ConditionVariable;
 pub use subscriber::SubscribeState;

iceoryx-sys/src/publisher.rs

@@ -2,9 +2,10 @@
 // SPDX-FileCopyrightText: © Contributors to the iceoryx-rs project
 // SPDX-FileContributor: Mathias Kraus
 
-use crate::PublisherOptions;
+use crate::{PublisherOptions, RawSampleMut};
 
 use std::ffi::{c_void, CString};
+use std::mem::MaybeUninit;
 
 cpp! {{
     #include "iceoryx_posh/internal/popo/ports/publisher_port_user.hpp"
@@ -104,38 +105,33 @@ impl Publisher {
         }
     }
 
-    pub fn try_allocate<T>(&self) -> Option<*mut T> {
+    pub fn try_allocate<T>(&self) -> Option<RawSampleMut<MaybeUninit<T>>> {
         let size = std::mem::size_of::<T>() as u32;
         let align = std::mem::align_of::<T>() as u32;
         unsafe {
-            let payload = self.try_allocate_chunk(size, align);
-
-            if !payload.is_null() {
-                Some(payload as *mut T)
-            } else {
-                None
-            }
+            self.try_allocate_chunk(size, align)
+                .map(|payload| payload.cast::<MaybeUninit<T>>())
         }
     }
 
-    pub fn try_allocate_slice<T>(&self, len: u32, align: u32) -> Option<*mut T> {
+    pub fn try_allocate_slice<T>(
+        &self,
+        len: u32,
+        align: u32,
+    ) -> Option<RawSampleMut<[MaybeUninit<T>]>> {
         unsafe {
             if align < std::mem::align_of::<T>() as u32 {
                 return None;
             }
 
             let size = len * std::mem::size_of::<T>() as u32;
-            let payload = self.try_allocate_chunk(size, align);
-
-            if !payload.is_null() {
-                Some(payload as *mut T)
-            } else {
-                None
-            }
+            self.try_allocate_chunk(size, align).map(|payload| {
+                RawSampleMut::slice_from_raw_parts(payload.cast::<MaybeUninit<T>>(), len as usize)
+            })
         }
     }
 
-    unsafe fn try_allocate_chunk(&self, size: u32, align: u32) -> *mut c_void {
+    unsafe fn try_allocate_chunk(&self, size: u32, align: u32) -> Option<RawSampleMut<c_void>> {
         let payload = cpp!([self as "PublisherPortUser*", size as "uint32_t", align as "uint32_t"] -> *mut std::ffi::c_void as "void*" {
             auto allocResult = self->tryAllocateChunk(size,
                                                       align,
@@ -147,21 +143,26 @@ impl Publisher {
                 return allocResult.value()->userPayload();
             }
         });
-        payload
+
+        if !payload.is_null() {
+            Some(RawSampleMut::new_unchecked(payload))
+        } else {
+            None
+        }
     }
 
-    pub fn release<T: ?Sized>(&self, payload: *mut T) {
+    pub fn release<T: ?Sized>(&self, sample: RawSampleMut<T>) {
         unsafe {
-            let payload = payload as *const c_void;
+            let payload = sample.cast::<c_void>().as_payload_ptr();
             cpp!([self as "PublisherPortUser*", payload as "void*"] {
                 auto header = iox::mepoo::ChunkHeader::fromUserPayload(payload);
                 self->releaseChunk(header);
             });
         }
     }
 
-    pub fn send<T: ?Sized>(&self, payload: *mut T) {
-        let payload = payload as *const c_void;
+    pub fn send<T: ?Sized>(&self, sample: RawSampleMut<T>) {
+        let payload = sample.cast::<c_void>().as_payload_ptr();
         unsafe {
             cpp!([self as "PublisherPortUser*", payload as "void*"] {
                 auto header = iox::mepoo::ChunkHeader::fromUserPayload(payload);

iceoryx-sys/src/sample.rs

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: © Contributors to the iceoryx-rs project
+// SPDX-FileContributor: Mathias Kraus
+
+use crate::ChunkHeader;
+
+use std::ffi::c_void;
+use std::fmt;
+use std::slice;
+
+/// A `*const T` non-zero sample pointer to the user payload.
+#[repr(transparent)]
+pub struct RawSample<T: ?Sized> {
+    payload: *const T,
+}
+
+impl<T: ?Sized> RawSample<T> {
+    /// Creates a new `RawSample`.
+    ///
+    /// # Safety
+    ///
+    /// `payload` must be non-null.
+    #[inline]
+    pub unsafe fn new_unchecked(payload: *const T) -> Self {
+        debug_assert!(
+            !payload.is_null(),
+            "RawSample::new_unchecked requires that the payload pointer is non-null"
+        );
+        Self { payload }
+    }
+
+    /// Creates a new `RawSample`.
+    #[allow(clippy::not_unsafe_ptr_arg_deref)] // false positive
+    #[inline]
+    pub fn new(payload: *const T) -> Option<Self> {
+        if !payload.is_null() {
+            // SAFETY: `payload` pointer is checked to be non-null
+            Some(unsafe { Self::new_unchecked(payload) })
+        } else {
+            None
+        }
+    }
+
+    /// Casts to a `RawSample` of another type.
+    #[must_use]
+    #[inline]
+    pub fn cast<U>(self) -> RawSample<U> {
+        // SAFETY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { RawSample::new_unchecked(self.as_payload_ptr().cast::<U>()) }
+    }
+
+    /// Acquires the underlying payload pointer as `*const` pointer.
+    #[must_use]
+    #[inline(always)]
+    pub fn as_payload_ptr(self) -> *const T {
+        self.payload
+    }
+
+    /// Returns a reference to the `ChunkHeader`.
+    #[must_use]
+    #[inline]
+    pub fn chunk_header(&self) -> &ChunkHeader {
+        // SAFTEY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { ChunkHeader::from_user_payload_unchecked(self.as_payload_ptr() as *const c_void) }
+    }
+}
+
+impl<T> RawSample<[T]> {
+    /// Creates a non-null raw slice from a thin payload pointer and a length.
+    ///
+    /// The `len` argument is the number of **elements**, not the number of bytes.
+    ///
+    /// This function is safe, but dereferencing the return value is unsafe.
+    /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
+    #[must_use]
+    #[inline]
+    pub fn slice_from_raw_parts(sample: RawSample<T>, len: usize) -> RawSample<[T]> {
+        // SAFETY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { Self::new_unchecked(slice::from_raw_parts(sample.as_payload_ptr(), len)) }
+    }
+
+    /// Returns the length of a non-null raw slice.
+    #[must_use]
+    #[inline]
+    pub fn len(self) -> usize {
+        // SAFETY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { (*self.as_payload_ptr()).len() }
+    }
+}
+
+impl<T: ?Sized> Clone for RawSample<T> {
+    #[inline(always)]
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<T: ?Sized> Copy for RawSample<T> {}
+
+impl<T: ?Sized> fmt::Debug for RawSample<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Pointer::fmt(&self.as_payload_ptr(), f)
+    }
+}
+
+impl<T: ?Sized> fmt::Pointer for RawSample<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Pointer::fmt(&self.as_payload_ptr(), f)
+    }
+}
+
+/// A `*mut T` non-zero sample pointer to the user payload.
+#[repr(transparent)]
+pub struct RawSampleMut<T: ?Sized> {
+    payload: *mut T,
+}
+
+impl<T: ?Sized> RawSampleMut<T> {
+    /// Creates a new `RawSampleMut`.
+    ///
+    /// # Safety
+    ///
+    /// `payload` must be non-null.
+    #[inline]
+    pub unsafe fn new_unchecked(payload: *mut T) -> Self {
+        debug_assert!(
+            !payload.is_null(),
+            "RawSampleMut::new_unchecked requires that the payload pointer is non-null"
+        );
+        Self { payload }
+    }
+
+    /// Creates a new `RawSampleMut`.
+    #[allow(clippy::not_unsafe_ptr_arg_deref)] // false positive
+    #[inline]
+    pub fn new(payload: *mut T) -> Option<Self> {
+        if !payload.is_null() {
+            // SAFETY: `payload` pointer is checked to be non-null
+            Some(unsafe { Self::new_unchecked(payload) })
+        } else {
+            None
+        }
+    }
+
+    /// Casts to a `RawSampleMut` of another type.
+    #[must_use]
+    #[inline]
+    pub fn cast<U>(self) -> RawSampleMut<U> {
+        // SAFETY: `self.as_payload_mut_ptr` returns a non-null ptr
+        unsafe { RawSampleMut::new_unchecked(self.as_payload_mut_ptr().cast::<U>()) }
+    }
+
+    /// Acquires the underlying payload pointer as `*const` pointer.
+    #[must_use]
+    #[inline(always)]
+    pub fn as_payload_ptr(self) -> *const T {
+        self.as_payload_mut_ptr()
+    }
+
+    /// Acquires the underlying payload pointer as `*mut` pointer.
+    #[must_use]
+    #[inline(always)]
+    pub fn as_payload_mut_ptr(self) -> *mut T {
+        self.payload
+    }
+
+    /// Returns a reference to the `ChunkHeader`.
+    #[must_use]
+    #[inline]
+    pub fn chunk_header(&self) -> &ChunkHeader {
+        // SAFTEY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { ChunkHeader::from_user_payload_unchecked(self.as_payload_ptr() as *const c_void) }
+    }
+}
+
+impl<T> RawSampleMut<[T]> {
+    /// Creates a non-null raw slice from a thin payload pointer and a length.
+    ///
+    /// The `len` argument is the number of **elements**, not the number of bytes.
+    ///
+    /// This function is safe, but dereferencing the return value is unsafe.
+    /// See the documentation of [`slice::from_raw_parts_mut`] for slice safety requirements.
+    #[must_use]
+    #[inline]
+    pub fn slice_from_raw_parts(sample: RawSampleMut<T>, len: usize) -> RawSampleMut<[T]> {
+        // SAFETY: `self.as_payload_mut_ptr` returns a non-null ptr
+        unsafe { Self::new_unchecked(slice::from_raw_parts_mut(sample.as_payload_mut_ptr(), len)) }
+    }
+
+    /// Returns the length of a non-null raw slice.
+    #[must_use]
+    #[inline]
+    pub fn len(self) -> usize {
+        // SAFETY: `self.as_payload_ptr` returns a non-null ptr
+        unsafe { (*self.as_payload_ptr()).len() }
+    }
+}
+
+impl<T: ?Sized> Clone for RawSampleMut<T> {
+    #[inline(always)]
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<T: ?Sized> Copy for RawSampleMut<T> {}
+
+impl<T: ?Sized> fmt::Debug for RawSampleMut<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Pointer::fmt(&self.as_payload_ptr(), f)
+    }
+}
+
+impl<T: ?Sized> fmt::Pointer for RawSampleMut<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Pointer::fmt(&self.as_payload_ptr(), f)
+    }
+}