From 85edc37c0a13c5ba477c7a7eeaa8133e41b25b0b Mon Sep 17 00:00:00 2001 From: mevinagrise Date: Thu, 26 Mar 2026 19:54:33 +0800 Subject: [PATCH 1/2] docs: add missing safety sections for public unsafe APIs --- src/lib.rs | 21 ++++++++++++++++++--- src/linked_list.rs | 5 +++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 32de2d1..3e1ef7b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -79,7 +79,12 @@ impl Heap { 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. 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::() - 1) & (!size_of::() + 1); @@ -109,7 +114,12 @@ impl Heap { 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. 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 +165,12 @@ impl Heap { 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 heap that + /// has not already been deallocated. pub unsafe fn dealloc(&mut self, ptr: NonNull, layout: Layout) { let size = max( layout.size().next_power_of_two(), diff --git a/src/linked_list.rs b/src/linked_list.rs index 7a15925..6a659db 100644 --- a/src/linked_list.rs +++ b/src/linked_list.rs @@ -30,6 +30,11 @@ impl LinkedList { } /// Push `item` to the front of the list + /// + /// # Safety + /// + /// `item` must be a valid, writable pointer. The caller must ensure the pointed value can be + /// used to store the next pointer for this intrusive linked list. pub unsafe fn push(&mut self, item: *mut usize) { *item = self.head as usize; self.head = item; From f916fb7ef650b12350d01a13c6753142350311e8 Mon Sep 17 00:00:00 2001 From: mevinagrise Date: Thu, 26 Mar 2026 22:52:29 +0800 Subject: [PATCH 2/2] docs: clarify additional safety requirements --- src/lib.rs | 13 +++++++++---- src/linked_list.rs | 5 +++-- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 3e1ef7b..b45eb7e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -84,7 +84,9 @@ impl Heap { /// # Safety /// /// The caller must ensure the memory range is valid, writable, and not currently managed by - /// any other allocator. The range must remain available for the lifetime of this heap. + /// 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::() - 1) & (!size_of::() + 1); @@ -119,7 +121,10 @@ impl Heap { /// # Safety /// /// The caller must ensure the memory range is valid, writable, and not currently managed by - /// any other allocator. The range must remain available for the lifetime of this heap. + /// 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); } @@ -169,8 +174,8 @@ impl Heap { /// /// # Safety /// - /// `ptr` and `layout` must exactly match a previous successful allocation from this heap that - /// has not already been deallocated. + /// `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, layout: Layout) { let size = max( layout.size().next_power_of_two(), diff --git a/src/linked_list.rs b/src/linked_list.rs index 6a659db..f312f58 100644 --- a/src/linked_list.rs +++ b/src/linked_list.rs @@ -33,8 +33,9 @@ impl LinkedList { /// /// # Safety /// - /// `item` must be a valid, writable pointer. The caller must ensure the pointed value can be - /// used to store the next pointer for this intrusive linked list. + /// `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;