Skip to content

Commit

Permalink
Improve docs for buddy system heap order explanation
Browse files Browse the repository at this point in the history
- Clarify that the real order of the buddy system is `ORDER - 1`.
- Treewide change of default `ORDER` to `33` to match the explanation.

Signed-off-by: bigsaltyfishes <[email protected]>
  • Loading branch information
bigsaltyfishes committed Sep 21, 2024
1 parent 1bf005a commit 999b7e0
Show file tree
Hide file tree
Showing 3 changed files with 16 additions and 10 deletions.
2 changes: 1 addition & 1 deletion benches/memory_allocator_benchmark.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions src/frame.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ 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
///
Expand All @@ -29,7 +29,7 @@ use spin::Mutex;
/// let num = frame.alloc(2);
/// assert_eq!(num, Some(0));
/// ```
pub struct FrameAllocator<const ORDER: usize = 32> {
pub struct FrameAllocator<const ORDER: usize = 33> {
// buddy system with max order of ORDER
free_list: [BTreeSet<usize>; ORDER],

Expand Down Expand Up @@ -175,7 +175,7 @@ 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();
/// let mut frame = LockedFrameAllocator::<33>::new();
/// assert!(frame.lock().alloc(1).is_none());
///
/// frame.lock().add_frame(0, 3);
Expand All @@ -185,7 +185,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> {
Expand Down
12 changes: 9 additions & 3 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,10 @@ pub use frame::*;
/// ```
/// use buddy_system_allocator::*;
/// # use core::mem::size_of;
/// let mut heap = Heap::<32>::empty();
/// // The 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>();
Expand Down Expand Up @@ -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 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>();
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 999b7e0

Please sign in to comment.