From ab066c3d689ba61492ff4fb24fe3ae46bf495e73 Mon Sep 17 00:00:00 2001
From: Mees Delzenne <mees.delzenne@gmail.com>
Date: Fri, 16 Feb 2024 17:30:41 +0100
Subject: [PATCH] Add docs

---
 core/src/allocator.rs      | 27 +++++++++++++++++++++++++--
 core/src/allocator/rust.rs | 10 +++++-----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/core/src/allocator.rs b/core/src/allocator.rs
index 7dd09660..37ccb027 100644
--- a/core/src/allocator.rs
+++ b/core/src/allocator.rs
@@ -11,18 +11,41 @@ pub use rust::RustAllocator;
 pub type RawMemPtr = *mut u8;
 
 /// The allocator interface
+///
+/// # Safety
+/// Failure to implement this trait correctly will result in undefined behavior.
+/// - `alloc` must return a either a null pointer or a pointer to an available region of memory
+/// atleast `size` bytes and aligned to the size of `usize`.
+/// - `realloc` must either return a null pointer or return a pointer to an available region of
+/// memory atleast `new_size` bytes and aligned to the size of `usize`.
+/// - `usable_size` must return the amount of available memory for any allocation allocated with
+/// this allocator.
 #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "allocator")))]
-pub trait Allocator {
+pub unsafe trait Allocator {
     /// Allocate new memory
-    unsafe fn alloc(&mut self, size: usize) -> RawMemPtr;
+    ///
+    ///
+    fn alloc(&mut self, size: usize) -> RawMemPtr;
 
     /// De-allocate previously allocated memory
+    ///
+    /// # Safety
+    /// Caller must ensure that the pointer that is being deallocated was allocated by the same
+    /// Allocator instance.
     unsafe fn dealloc(&mut self, ptr: RawMemPtr);
 
     /// Re-allocate previously allocated memory
+    ///
+    /// # Safety
+    /// Caller must ensure that the pointer points to an allocation that was allocated by the same
+    /// Allocator instance.
     unsafe fn realloc(&mut self, ptr: RawMemPtr, new_size: usize) -> RawMemPtr;
 
     /// Get usable size of allocated memory region
+    ///
+    /// # Safety
+    /// Caller must ensure that the pointer handed to this function points to an allocation
+    /// allocated by the same allocator instance.
     unsafe fn usable_size(ptr: RawMemPtr) -> usize
     where
         Self: Sized;
diff --git a/core/src/allocator/rust.rs b/core/src/allocator/rust.rs
index 7ba36dca..6eba6ed8 100644
--- a/core/src/allocator/rust.rs
+++ b/core/src/allocator/rust.rs
@@ -37,8 +37,8 @@ fn round_size(size: usize) -> usize {
 /// The allocator which uses Rust global allocator
 pub struct RustAllocator;
 
-impl Allocator for RustAllocator {
-    unsafe fn alloc(&mut self, size: usize) -> RawMemPtr {
+unsafe impl Allocator for RustAllocator {
+    fn alloc(&mut self, size: usize) -> RawMemPtr {
         let size = round_size(size);
         let alloc_size = size + HEADER_SIZE;
         let layout = if let Ok(layout) = Layout::from_size_align(alloc_size, ALLOC_ALIGN) {
@@ -98,7 +98,7 @@ impl Allocator for RustAllocator {
     }
 
     #[allow(clippy::not_unsafe_ptr_arg_deref)]
-    fn usable_size(ptr: RawMemPtr) -> usize {
+    unsafe fn usable_size(ptr: RawMemPtr) -> usize {
         let ptr = unsafe { ptr.sub(HEADER_SIZE) };
         let header = unsafe { &*(ptr as *const Header) };
         header.size
@@ -115,7 +115,7 @@ mod test {
 
     struct TestAllocator;
 
-    impl Allocator for TestAllocator {
+    unsafe impl Allocator for TestAllocator {
         unsafe fn alloc(&mut self, size: usize) -> crate::allocator::RawMemPtr {
             let res = RustAllocator.alloc(size);
             ALLOC_SIZE.fetch_add(RustAllocator::usable_size(res), Ordering::AcqRel);
@@ -143,7 +143,7 @@ mod test {
             res
         }
 
-        fn usable_size(ptr: crate::allocator::RawMemPtr) -> usize
+        unsafe fn usable_size(ptr: crate::allocator::RawMemPtr) -> usize
         where
             Self: Sized,
         {