diff --git a/src/lib.rs b/src/lib.rs index 32de2d1..b45eb7e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -79,7 +79,14 @@ 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 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); @@ -109,7 +116,15 @@ 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. 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 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 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 7a15925..f312f58 100644 --- a/src/linked_list.rs +++ b/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;