shm-primitives 0.2.1

Lock-free primitives for shared memory IPC: BipBuffer, slot metadata, and OS-level doorbell/mmap
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use core::mem::{align_of, size_of};
use core::ptr::NonNull;

/// A contiguous region of memory addressed by offset.
///
/// # Safety
///
/// The caller must ensure:
/// - `base` is valid for `len` bytes and properly aligned for all contained types
/// - the memory remains valid for the lifetime of this Region
#[derive(Clone, Copy)]
pub struct Region {
    base: NonNull<u8>,
    len: usize,
}

impl Region {
    /// Create a region from a raw pointer and length.
    ///
    /// # Safety
    ///
    /// - `base` must be valid for `len` bytes
    /// - `base` must be aligned for all contained types
    /// - the memory must remain valid for the lifetime of this Region
    pub unsafe fn from_raw(base: *mut u8, len: usize) -> Self {
        let base = NonNull::new(base).expect("region base must be non-null");
        Self { base, len }
    }

    /// Returns the base pointer of the region.
    #[inline]
    pub fn as_ptr(&self) -> *mut u8 {
        self.base.as_ptr()
    }

    /// Returns the size of the region in bytes.
    #[inline]
    pub fn len(&self) -> usize {
        self.len
    }

    /// Returns true if the region has zero length.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Returns a pointer to offset `off` within the region.
    #[inline]
    pub fn offset(&self, off: usize) -> *mut u8 {
        assert!(
            off < self.len,
            "offset {off} out of bounds (len={})",
            self.len
        );
        unsafe { self.as_ptr().add(off) }
    }

    /// Returns a reference to a `T` at the given byte offset.
    ///
    /// # Safety
    ///
    /// The offset must be aligned for `T` and within bounds.
    #[inline]
    pub unsafe fn get<T>(&self, off: usize) -> &T {
        debug_assert!(off + size_of::<T>() <= self.len);
        debug_assert!(off.is_multiple_of(align_of::<T>()));
        unsafe { &*(self.offset(off) as *const T) }
    }

    /// Returns a mutable reference to a `T` at the given byte offset.
    ///
    /// # Safety
    ///
    /// The offset must be aligned for `T` and within bounds.
    #[inline]
    #[allow(clippy::mut_from_ref)]
    pub unsafe fn get_mut<T>(&self, off: usize) -> &mut T {
        debug_assert!(off + size_of::<T>() <= self.len);
        debug_assert!(off.is_multiple_of(align_of::<T>()));
        unsafe { &mut *(self.offset(off) as *mut T) }
    }
}

unsafe impl Send for Region {}
unsafe impl Sync for Region {}

mod heap {
    use super::Region;
    use core::ptr::NonNull;
    use std::alloc::{Layout, alloc_zeroed, dealloc};

    /// Heap-backed region for tests or heap-based usage.
    pub struct HeapRegion {
        base: NonNull<u8>,
        len: usize,
        layout: Layout,
    }

    impl HeapRegion {
        /// Allocate a zeroed heap region aligned to 64 bytes.
        pub fn new_zeroed(size: usize) -> Self {
            let layout =
                Layout::from_size_align(size.max(1), 64).expect("invalid heap region layout");
            let ptr = unsafe { alloc_zeroed(layout) };
            let base = NonNull::new(ptr).expect("heap region allocation failed");
            Self {
                base,
                len: size,
                layout,
            }
        }

        /// Returns a Region view of this allocation.
        #[inline]
        pub fn region(&self) -> Region {
            unsafe { Region::from_raw(self.base.as_ptr(), self.len) }
        }

        /// Returns the allocation size.
        #[inline]
        pub fn len(&self) -> usize {
            self.len
        }

        /// Returns true if the allocation is zero-length.
        #[inline]
        pub fn is_empty(&self) -> bool {
            self.len == 0
        }
    }

    impl Drop for HeapRegion {
        fn drop(&mut self) {
            unsafe { dealloc(self.base.as_ptr(), self.layout) };
        }
    }

    unsafe impl Send for HeapRegion {}
    unsafe impl Sync for HeapRegion {}
}

pub use heap::HeapRegion;