Skip to content

Commit 00fd9f7

Browse files
Improve docs for buddy system heap order explanation
- 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]>
1 parent 1bf005a commit 00fd9f7

File tree

4 files changed

+22
-14
lines changed

4 files changed

+22
-14
lines changed

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ To use buddy_system_allocator for global allocator:
1313
use buddy_system_allocator::LockedHeap;
1414

1515
#[global_allocator]
16-
static HEAP_ALLOCATOR: LockedHeap = LockedHeap::<32>::empty();
16+
static HEAP_ALLOCATOR: LockedHeap = LockedHeap::<33>::empty();
1717
```
1818

1919
To init the allocator:

benches/memory_allocator_benchmark.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ pub fn thread_test() {
138138
}
139139
}
140140

141-
const ORDER: usize = 32;
141+
const ORDER: usize = 33;
142142
const MACHINE_ALIGN: usize = core::mem::size_of::<usize>();
143143
/// for now 128M is needed
144144
/// TODO: reduce memory use

src/frame.rs

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,17 @@ use spin::Mutex;
1111

1212
/// A frame allocator that uses buddy system, requiring a global allocator.
1313
///
14-
/// The max order of the allocator is specified via the const generic parameter `ORDER`. The frame
15-
/// allocator will only be able to allocate ranges of size up to 2<sup>ORDER</sup>, out of a total
16-
/// range of size at most 2<sup>ORDER + 1</sup> - 1.
14+
/// The max order of the allocator is determined by the const generic parameter `ORDER` (`MAX_ORDER = ORDER - 1`).
15+
/// The frame allocator will only be able to allocate ranges of size up to 2<sup>MAX_ORDER</sup>, out of a total
16+
/// range of size at most 2<sup>MAX_ORDER + 1</sup> - 1.
1717
///
1818
/// # Usage
1919
///
2020
/// Create a frame allocator and add some frames to it:
2121
/// ```
2222
/// use buddy_system_allocator::*;
23-
/// let mut frame = FrameAllocator::<32>::new();
23+
/// // Notice that the max order is `ORDER - 1`.
24+
/// let mut frame = FrameAllocator::<33>::new();
2425
/// assert!(frame.alloc(1).is_none());
2526
///
2627
/// frame.add_frame(0, 3);
@@ -29,8 +30,8 @@ use spin::Mutex;
2930
/// let num = frame.alloc(2);
3031
/// assert_eq!(num, Some(0));
3132
/// ```
32-
pub struct FrameAllocator<const ORDER: usize = 32> {
33-
// buddy system with max order of ORDER
33+
pub struct FrameAllocator<const ORDER: usize = 33> {
34+
// buddy system with max order of `ORDER - 1`
3435
free_list: [BTreeSet<usize>; ORDER],
3536

3637
// statistics
@@ -175,7 +176,8 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
175176
/// Create a locked frame allocator and add frames to it:
176177
/// ```
177178
/// use buddy_system_allocator::*;
178-
/// let mut frame = LockedFrameAllocator::<32>::new();
179+
/// // Notice that the max order is `ORDER - 1`.
180+
/// let mut frame = LockedFrameAllocator::<33>::new();
179181
/// assert!(frame.lock().alloc(1).is_none());
180182
///
181183
/// frame.lock().add_frame(0, 3);
@@ -185,7 +187,7 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
185187
/// assert_eq!(num, Some(0));
186188
/// ```
187189
#[cfg(feature = "use_spin")]
188-
pub struct LockedFrameAllocator<const ORDER: usize = 32>(Mutex<FrameAllocator<ORDER>>);
190+
pub struct LockedFrameAllocator<const ORDER: usize = 33>(Mutex<FrameAllocator<ORDER>>);
189191

190192
#[cfg(feature = "use_spin")]
191193
impl<const ORDER: usize> LockedFrameAllocator<ORDER> {

src/lib.rs

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,10 @@ pub use frame::*;
3939
/// ```
4040
/// use buddy_system_allocator::*;
4141
/// # use core::mem::size_of;
42-
/// let mut heap = Heap::<32>::empty();
42+
/// // The max order of the buddy system is `ORDER - 1`.
43+
/// // For example, to create a heap with a maximum block size of 2^32 bytes,
44+
/// // you should define the heap with `ORDER = 33`.
45+
/// let mut heap = Heap::<33>::empty();
4346
/// # let space: [usize; 100] = [0; 100];
4447
/// # let begin: usize = space.as_ptr() as usize;
4548
/// # let end: usize = begin + 100 * size_of::<usize>();
@@ -51,7 +54,7 @@ pub use frame::*;
5154
/// }
5255
/// ```
5356
pub struct Heap<const ORDER: usize> {
54-
// buddy system with max order of `ORDER`
57+
// buddy system with max order of `ORDER - 1`
5558
free_list: [linked_list::LinkedList; ORDER],
5659

5760
// statistics
@@ -229,7 +232,10 @@ impl<const ORDER: usize> fmt::Debug for Heap<ORDER> {
229232
/// ```
230233
/// use buddy_system_allocator::*;
231234
/// # use core::mem::size_of;
232-
/// let mut heap = LockedHeap::<32>::new();
235+
/// // The max order of the buddy system is `ORDER - 1`.
236+
/// // For example, to create a heap with a maximum block size of 2^32 bytes,
237+
/// // you should define the heap with `ORDER = 33`.
238+
/// let mut heap = LockedHeap::<33>::new();
233239
/// # let space: [usize; 100] = [0; 100];
234240
/// # let begin: usize = space.as_ptr() as usize;
235241
/// # let end: usize = begin + 100 * size_of::<usize>();
@@ -287,7 +293,7 @@ unsafe impl<const ORDER: usize> GlobalAlloc for LockedHeap<ORDER> {
287293
/// Create a locked heap:
288294
/// ```
289295
/// use buddy_system_allocator::*;
290-
/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<32>, layout: &core::alloc::Layout| {});
296+
/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<33>, layout: &core::alloc::Layout| {});
291297
/// ```
292298
///
293299
/// Before oom, the allocator will try to call rescue function and try for one more time.

0 commit comments

Comments
 (0)