kalloc/
allocator.rs

1// Copyright 2026 The Fuchsia Authors
2//
3// Use of this source code is governed by a MIT-style
4// license that can be found in the LICENSE file or at
5// https://opensource.org/licenses/MIT
6
7use core::alloc::Layout;
8use core::ptr::NonNull;
9
10/// Error type for allocation failures.
11#[derive(Debug, Eq, PartialEq)]
12pub struct AllocError;
13
14impl core::fmt::Display for AllocError {
15    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
16        f.write_str("allocation failure")
17    }
18}
19
20impl core::error::Error for AllocError {}
21
22/// Trait for allocators used by Box and other collections.
23///
24/// This trait mirrors the `core::alloc::Allocator` trait,
25/// returning `Result<NonNull<[u8]>, AllocError>` to provide the actual
26/// size allocated.
27///
28/// Implementations of this trait must tolerate being passed zero-sized layouts.
29/// For zero-sized allocations, implementations should return a dangling pointer
30/// with the appropriate alignment, and `deallocate` should be a no-op for such pointers.
31pub trait Allocator: Clone {
32    /// Allocates memory as described by the given `layout`.
33    ///
34    /// If the layout has a size of zero, this method returns a dangling pointer.
35    fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
36
37    /// # Safety
38    ///
39    /// - The pointer must have been allocated by `allocate` with the same layout.
40    ///
41    /// If the layout has a size of zero, this method is a no-op.
42    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout);
43
44    /// # Safety
45    ///
46    /// - `ptr` must denote a block of memory currently allocated via this allocator.
47    /// - `old_layout` must fit that block of memory (The `new_layout` argument need not fit it.).
48    /// - `new_layout.size()` must be greater than or equal to `old_layout.size()`.
49    ///
50    /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
51    ///
52    /// If the new layout has a size of zero, this method returns a dangling pointer.
53    unsafe fn grow(
54        &self,
55        ptr: NonNull<u8>,
56        old_layout: Layout,
57        new_layout: Layout,
58    ) -> Result<NonNull<[u8]>, AllocError>;
59
60    /// # Safety
61    ///
62    /// - `ptr` must denote a block of memory currently allocated via this allocator.
63    /// - `old_layout` must fit that block of memory (The `new_layout` argument need not fit it.).
64    /// - `new_layout.size()` must be less than or equal to `old_layout.size()`.
65    ///
66    /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
67    ///
68    /// If the new layout has a size of zero, this method deallocates the memory and returns a dangling pointer.
69    unsafe fn shrink(
70        &self,
71        ptr: NonNull<u8>,
72        old_layout: Layout,
73        new_layout: Layout,
74    ) -> Result<NonNull<[u8]>, AllocError>;
75
76    /// Allocates zeroed memory as described by the given `layout`.
77    ///
78    /// If the layout has a size of zero, this method returns a dangling pointer.
79    fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
80}
81
82/// Default allocator that uses the global allocator (userspace) or kernel allocator.
83#[derive(Clone, Default)]
84pub struct DefaultAllocator;
85
86impl Allocator for DefaultAllocator {
87    fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
88        if layout.size() == 0 {
89            return Ok(NonNull::from_ref(&[]));
90        }
91        let ptr = unsafe { crate::alloc(layout).ok_or(AllocError)? };
92        Ok(NonNull::slice_from_raw_parts(ptr, layout.size()))
93    }
94
95    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
96        if layout.size() == 0 {
97            return;
98        }
99        unsafe { crate::dealloc(ptr.as_ptr(), layout) }
100    }
101
102    unsafe fn grow(
103        &self,
104        ptr: NonNull<u8>,
105        old_layout: Layout,
106        new_layout: Layout,
107    ) -> Result<NonNull<[u8]>, AllocError> {
108        assert!(new_layout.size() >= old_layout.size());
109        if new_layout.size() == 0 {
110            return Ok(NonNull::from_ref(&[]));
111        }
112        if old_layout.size() == 0 {
113            return self.allocate(new_layout);
114        }
115        let ptr = unsafe {
116            crate::realloc(ptr.as_ptr(), old_layout, new_layout.size()).ok_or(AllocError)?
117        };
118        Ok(NonNull::slice_from_raw_parts(ptr, new_layout.size()))
119    }
120
121    unsafe fn shrink(
122        &self,
123        ptr: NonNull<u8>,
124        old_layout: Layout,
125        new_layout: Layout,
126    ) -> Result<NonNull<[u8]>, AllocError> {
127        assert!(new_layout.size() <= old_layout.size());
128        if new_layout.size() == 0 {
129            unsafe { self.deallocate(ptr, old_layout) };
130            return Ok(NonNull::from_ref(&[]));
131        }
132        if old_layout.size() == 0 {
133            return Ok(NonNull::from_ref(&[]));
134        }
135        let ptr = unsafe {
136            crate::realloc(ptr.as_ptr(), old_layout, new_layout.size()).ok_or(AllocError)?
137        };
138        Ok(NonNull::slice_from_raw_parts(ptr, new_layout.size()))
139    }
140
141    fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
142        if layout.size() == 0 {
143            return Ok(NonNull::from_ref(&[]));
144        }
145        let ptr = unsafe { crate::alloc_zeroed(layout).ok_or(AllocError)? };
146        Ok(NonNull::slice_from_raw_parts(ptr, layout.size()))
147    }
148}
149
150/// An allocator that does not perform any actual allocation or deallocation.
151///
152/// This is useful when constructing Box and other dynamically allocated collections from raw
153/// pointers to pre-existing memory that is owned and managed elsewhere (e.g., by C++ code), to
154/// ensure that dropping the collection does not deallocate the underlying memory.
155#[derive(Clone, Default)]
156pub struct NoOpAllocator;
157
158impl Allocator for NoOpAllocator {
159    fn allocate(&self, _layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
160        Err(AllocError)
161    }
162
163    unsafe fn deallocate(&self, _ptr: NonNull<u8>, _layout: Layout) {
164        // No-op.
165    }
166
167    unsafe fn grow(
168        &self,
169        _ptr: NonNull<u8>,
170        _old_layout: Layout,
171        _new_layout: Layout,
172    ) -> Result<NonNull<[u8]>, AllocError> {
173        Err(AllocError)
174    }
175
176    unsafe fn shrink(
177        &self,
178        _ptr: NonNull<u8>,
179        _old_layout: Layout,
180        _new_layout: Layout,
181    ) -> Result<NonNull<[u8]>, AllocError> {
182        Err(AllocError)
183    }
184
185    fn allocate_zeroed(&self, _layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
186        Err(AllocError)
187    }
188}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193
194    #[test]
195    fn test_default_allocator() {
196        let layout = Layout::from_size_align(10, 1).unwrap();
197        let ptr = DefaultAllocator::default().allocate(layout).unwrap();
198        unsafe {
199            DefaultAllocator::default().deallocate(ptr.cast::<u8>(), layout);
200        }
201    }
202
203    #[test]
204    fn test_default_allocator_grow_shrink() {
205        let layout = Layout::from_size_align(10, 1).unwrap();
206        let ptr = DefaultAllocator::default().allocate(layout).unwrap();
207
208        let new_layout = Layout::from_size_align(20, 1).unwrap();
209        let grown_ptr = unsafe {
210            DefaultAllocator::default().grow(ptr.cast::<u8>(), layout, new_layout).unwrap()
211        };
212        assert!(grown_ptr.len() >= 20);
213
214        let shrunk_layout = Layout::from_size_align(5, 1).unwrap();
215        let shrunk_ptr = unsafe {
216            DefaultAllocator::default()
217                .shrink(grown_ptr.cast::<u8>(), new_layout, shrunk_layout)
218                .unwrap()
219        };
220        assert!(shrunk_ptr.len() >= 5);
221
222        unsafe {
223            DefaultAllocator::default().deallocate(shrunk_ptr.cast::<u8>(), shrunk_layout);
224        }
225    }
226
227    #[test]
228    fn test_default_allocator_zeroed() {
229        let layout = Layout::from_size_align(10, 1).unwrap();
230        let ptr = DefaultAllocator::default().allocate_zeroed(layout).unwrap();
231
232        // Verify it is zeroed!
233        let slice = unsafe { ptr.as_ref() };
234        for &b in slice {
235            assert_eq!(b, 0);
236        }
237
238        unsafe {
239            DefaultAllocator::default().deallocate(ptr.cast::<u8>(), layout);
240        }
241    }
242
243    #[test]
244    fn test_default_allocator_zero_sized() {
245        let allocator = DefaultAllocator::default();
246
247        let layout0 = Layout::from_size_align(0, 1).unwrap();
248        let ptr0 = allocator.allocate(layout0).unwrap();
249        assert_eq!(ptr0.len(), 0);
250
251        let ptr0_zeroed = allocator.allocate_zeroed(layout0).unwrap();
252        assert_eq!(ptr0_zeroed.len(), 0);
253
254        unsafe {
255            allocator.deallocate(ptr0.cast::<u8>(), layout0);
256            allocator.deallocate(ptr0_zeroed.cast::<u8>(), layout0);
257        }
258
259        let grown0 = unsafe { allocator.grow(ptr0.cast::<u8>(), layout0, layout0).unwrap() };
260        assert_eq!(grown0.len(), 0);
261
262        let layout10 = Layout::from_size_align(10, 1).unwrap();
263        let grown10 = unsafe { allocator.grow(ptr0.cast::<u8>(), layout0, layout10).unwrap() };
264        assert!(grown10.len() >= 10);
265
266        let shrunk0 = unsafe { allocator.shrink(grown10.cast::<u8>(), layout10, layout0).unwrap() };
267        assert_eq!(shrunk0.len(), 0);
268
269        let shrunk0_again =
270            unsafe { allocator.shrink(ptr0.cast::<u8>(), layout0, layout0).unwrap() };
271        assert_eq!(shrunk0_again.len(), 0);
272    }
273
274    #[test]
275    fn test_no_op_allocator() {
276        let allocator = NoOpAllocator;
277        let layout = Layout::from_size_align(10, 1).unwrap();
278
279        // allocate and allocate_zeroed should return Err
280        assert_eq!(allocator.allocate(layout), Err(AllocError));
281        assert_eq!(allocator.allocate_zeroed(layout), Err(AllocError));
282
283        // grow and shrink should return Err
284        let ptr = NonNull::dangling();
285        assert_eq!(unsafe { allocator.grow(ptr, layout, layout) }, Err(AllocError));
286        assert_eq!(unsafe { allocator.shrink(ptr, layout, layout) }, Err(AllocError));
287
288        // deallocate should not panic or do anything (no-op)
289        unsafe {
290            allocator.deallocate(ptr, layout);
291        }
292    }
293}
kalloc/allocator.rs

kalloc/
allocator.rs
