Merge pull request #45 from mevinagrise/docs-safety-sections

docs: add missing safety sections for public unsafe APIs

Author: jiegec

src/lib.rs

@@ -79,7 +79,14 @@ impl<const ORDER: usize> Heap<ORDER> {
         Self::new()
     }
 
-    /// Add a range of memory [start, end) to the heap
+    /// Add a range of memory `[start, end)` to the heap.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure the memory range is valid, writable, and not currently managed by
+    /// any other allocator or by this `Heap`. In particular, the provided `[start, end)` range
+    /// must not overlap with any memory region that has already been added to this `Heap`. The
+    /// range must remain available for the lifetime of this heap.
     pub unsafe fn add_to_heap(&mut self, mut start: usize, mut end: usize) {
         // avoid unaligned access on some platforms
         start = (start + size_of::<usize>() - 1) & (!size_of::<usize>() + 1);
@@ -109,7 +116,15 @@ impl<const ORDER: usize> Heap<ORDER> {
         self.total += total;
     }
 
-    /// Add a range of memory [start, start+size) to the heap
+    /// Add a range of memory `[start, start + size)` to the heap.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure the memory range is valid, writable, and not currently managed by
+    /// any other allocator. Additionally, the range `[start, start + size)` must be disjoint from
+    /// every memory region previously added to this heap instance, whether via
+    /// [`Heap::add_to_heap`] or [`Heap::init`]. The range must remain available for the lifetime
+    /// of this heap.
     pub unsafe fn init(&mut self, start: usize, size: usize) {
         self.add_to_heap(start, start + size);
     }
@@ -155,7 +170,12 @@ impl<const ORDER: usize> Heap<ORDER> {
         Err(())
     }
 
-    /// Dealloc a range of memory from the heap
+    /// Dealloc a range of memory from the heap.
+    ///
+    /// # Safety
+    ///
+    /// `ptr` and `layout` must exactly match a previous successful allocation from this specific
+    /// `Heap` instance, and that allocation must not already have been deallocated.
     pub unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout) {
         let size = max(
             layout.size().next_power_of_two(),

src/linked_list.rs

@@ -30,6 +30,12 @@ impl LinkedList {
     }
 
     /// Push `item` to the front of the list
+    ///
+    /// # Safety
+    ///
+    /// `item` must be a valid, writable pointer, properly aligned for `usize` reads and writes.
+    /// The caller must ensure that the pointed value can be used to store the next pointer for
+    /// this intrusive linked list, and remains valid for as long as it is contained in the list.
     pub unsafe fn push(&mut self, item: *mut usize) {
         *item = self.head as usize;
         self.head = item;