Merge pull request #36 from bigsaltyfishes/master

Improve documentation for buddy system heap order explanation

README.md

@@ -13,7 +13,7 @@ To use buddy_system_allocator for global allocator:
 use buddy_system_allocator::LockedHeap;
 
 #[global_allocator]
-static HEAP_ALLOCATOR: LockedHeap = LockedHeap::<32>::empty();
+static HEAP_ALLOCATOR: LockedHeap = LockedHeap::<33>::empty();
 ```
 
 To init the allocator:

benches/memory_allocator_benchmark.rs

@@ -138,7 +138,7 @@ pub fn thread_test() {
     }
 }
 
-const ORDER: usize = 32;
+const ORDER: usize = 33;
 const MACHINE_ALIGN: usize = core::mem::size_of::<usize>();
 /// for now 128M is needed
 /// TODO: reduce memory use

src/frame.rs

@@ -11,16 +11,17 @@ use spin::Mutex;
 
 /// A frame allocator that uses buddy system, requiring a global allocator.
 ///
-/// The max order of the allocator is specified via the const generic parameter `ORDER`. The frame
-/// allocator will only be able to allocate ranges of size up to 2<sup>ORDER</sup>, out of a total
-/// range of size at most 2<sup>ORDER + 1</sup> - 1.
+/// The max order of the allocator is determined by the const generic parameter `ORDER` (`MAX_ORDER = ORDER - 1`). 
+/// The frame allocator will only be able to allocate ranges of size up to 2<sup>MAX_ORDER</sup>, out of a total
+/// range of size at most 2<sup>MAX_ORDER + 1</sup> - 1.
 ///
 /// # Usage
 ///
 /// Create a frame allocator and add some frames to it:
 /// ```
 /// use buddy_system_allocator::*;
-/// let mut frame = FrameAllocator::<32>::new();
+/// // Notice that the max order is `ORDER - 1`.
+/// let mut frame = FrameAllocator::<33>::new();
 /// assert!(frame.alloc(1).is_none());
 ///
 /// frame.add_frame(0, 3);
@@ -29,8 +30,8 @@ use spin::Mutex;
 /// let num = frame.alloc(2);
 /// assert_eq!(num, Some(0));
 /// ```
-pub struct FrameAllocator<const ORDER: usize = 32> {
-    // buddy system with max order of ORDER
+pub struct FrameAllocator<const ORDER: usize = 33> {
+    // buddy system with max order of `ORDER - 1`
     free_list: [BTreeSet<usize>; ORDER],
 
     // statistics
@@ -175,7 +176,8 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
 /// Create a locked frame allocator and add frames to it:
 /// ```
 /// use buddy_system_allocator::*;
-/// let mut frame = LockedFrameAllocator::<32>::new();
+/// // Notice that the max order is `ORDER - 1`.
+/// let mut frame = LockedFrameAllocator::<33>::new();
 /// assert!(frame.lock().alloc(1).is_none());
 ///
 /// frame.lock().add_frame(0, 3);
@@ -185,7 +187,7 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
 /// assert_eq!(num, Some(0));
 /// ```
 #[cfg(feature = "use_spin")]
-pub struct LockedFrameAllocator<const ORDER: usize = 32>(Mutex<FrameAllocator<ORDER>>);
+pub struct LockedFrameAllocator<const ORDER: usize = 33>(Mutex<FrameAllocator<ORDER>>);
 
 #[cfg(feature = "use_spin")]
 impl<const ORDER: usize> LockedFrameAllocator<ORDER> {

src/lib.rs

@@ -39,7 +39,10 @@ pub use frame::*;
 /// ```
 /// use buddy_system_allocator::*;
 /// # use core::mem::size_of;
-/// let mut heap = Heap::<32>::empty();
+/// // The max order of the buddy system is `ORDER - 1`.
+/// // For example, to create a heap with a maximum block size of 2^32 bytes,
+/// // you should define the heap with `ORDER = 33`.
+/// let mut heap = Heap::<33>::empty();
 /// # let space: [usize; 100] = [0; 100];
 /// # let begin: usize = space.as_ptr() as usize;
 /// # let end: usize = begin + 100 * size_of::<usize>();
@@ -51,7 +54,7 @@ pub use frame::*;
 /// }
 /// ```
 pub struct Heap<const ORDER: usize> {
-    // buddy system with max order of `ORDER`
+    // buddy system with max order of `ORDER - 1`
     free_list: [linked_list::LinkedList; ORDER],
 
     // statistics
@@ -229,7 +232,10 @@ impl<const ORDER: usize> fmt::Debug for Heap<ORDER> {
 /// ```
 /// use buddy_system_allocator::*;
 /// # use core::mem::size_of;
-/// let mut heap = LockedHeap::<32>::new();
+/// // The max order of the buddy system is `ORDER - 1`.
+/// // For example, to create a heap with a maximum block size of 2^32 bytes,
+/// // you should define the heap with `ORDER = 33`.
+/// let mut heap = LockedHeap::<33>::new();
 /// # let space: [usize; 100] = [0; 100];
 /// # let begin: usize = space.as_ptr() as usize;
 /// # let end: usize = begin + 100 * size_of::<usize>();
@@ -287,7 +293,7 @@ unsafe impl<const ORDER: usize> GlobalAlloc for LockedHeap<ORDER> {
 /// Create a locked heap:
 /// ```
 /// use buddy_system_allocator::*;
-/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<32>, layout: &core::alloc::Layout| {});
+/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<33>, layout: &core::alloc::Layout| {});
 /// ```
 ///
 /// Before oom, the allocator will try to call rescue function and try for one more time.

src/test.rs

@@ -69,7 +69,7 @@ fn test_heap_add_large() {
     // 512 bytes of space
     let space: [u8; 512] = [0; 512];
     unsafe {
-        heap.add_to_heap(space.as_ptr() as usize, space.as_ptr().add(100) as usize);
+        heap.add_to_heap(space.as_ptr() as usize, space.as_ptr().add(512) as usize);
     }
     let addr = heap.alloc(Layout::from_size_align(1, 1).unwrap());
     assert!(addr.is_ok());