1 // SPDX-License-Identifier: GPL-2.0
21 /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
24 /// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
32 /// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
61 /// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
62 /// zero-sized types, is a dangling, well aligned pointer.
64 pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
66 /// Type alias for [`Box`] with a [`Kmalloc`] allocator.
78 /// Type alias for [`Box`] with a [`Vmalloc`] allocator.
90 /// Type alias for [`Box`] with a [`KVmalloc`] allocator.
102 // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
103 unsafe impl<T, A> Send for Box<T, A>
106     A: Allocator,
110 // SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`.
111 unsafe impl<T, A> Sync for Box<T, A>
114     A: Allocator,
118 impl<T, A> Box<T, A>
121     A: Allocator,
123     /// Creates a new `Box<T, A>` from a raw pointer.
127     /// For non-ZSTs, `raw` must point at an allocation allocated with `A` that is sufficiently
128     /// aligned for and holds a valid `T`. The caller passes ownership of the allocation to the
131     /// For ZSTs, `raw` must be a dangling, well aligned pointer.
133     pub const unsafe fn from_raw(raw: *mut T) -> Self {  in from_raw()
135         // SAFETY: By the safety preconditions of this function, `raw` is not a NULL pointer.  in from_raw()
139     /// Consumes the `Box<T, A>` and returns a raw pointer.
141     /// This will not run the destructor of `T` and for non-ZSTs the allocation will stay alive
150     /// // SAFETY: `ptr` comes from a previous call to `KBox::into_raw`.
157     pub fn into_raw(b: Self) -> *mut T {  in into_raw()
161     /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
165     pub fn leak<'a>(b: Self) -> &'a mut T {  in leak()
166         // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer  in leak()
172 impl<T, A> Box<MaybeUninit<T>, A>
174     A: Allocator,
176     /// Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`.
184     pub unsafe fn assume_init(self) -> Box<T, A> {  in assume_init()  argument
187         // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements  in assume_init()
189         // safe to reconstruct the `Box` as `Box<T, A>`.  in assume_init()
193     /// Writes the value and converts to `Box<T, A>`.
194     pub fn write(mut self, value: T) -> Box<T, A> {  in write()  argument
202 impl<T, A> Box<T, A>
204     A: Allocator,
206     /// Creates a new `Box<T, A>` and initializes its contents with `x`.
208     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
210     pub fn new(x: T, flags: Flags) -> Result<Self, AllocError> {  in new()
215     /// Creates a new `Box<T, A>` with uninitialized contents.
217     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
229     pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {  in new_uninit()  argument
231         let ptr = A::alloc(layout, flags)?;  in new_uninit()
233         // INVARIANT: `ptr` is either a dangling pointer or points to memory allocated with `A`,  in new_uninit()
234         // which is sufficient in size and alignment for storing a `T`.  in new_uninit()
238     /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be
241     pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>  in pin()  argument
243         A: 'static,  in pin()
249     fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in forget_contents()  argument
264     /// // Now we can re-use `value`:
269     pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in drop_contents()  argument
280     pub fn into_inner(b: Self) -> T {  in into_inner()
288 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
291     A: Allocator,
293     /// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
297     fn from(b: Box<T, A>) -> Self {  in from()
298         // SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long  in from()
304 impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>
306     A: Allocator + 'static,
308     type Initialized = Box<T, A>;
310     fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {  in write_init()
319     fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {  in write_pin_init()
329 impl<T, A> InPlaceInit<T> for Box<T, A>
331     A: Allocator + 'static,
336     fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Pin<Self>, E>  in try_pin_init()
340         Box::<_, A>::new_uninit(flags)?.write_pin_init(init)  in try_pin_init()
344     fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>  in try_init()
348         Box::<_, A>::new_uninit(flags)?.write_init(init)  in try_init()
352 impl<T: 'static, A> ForeignOwnable for Box<T, A>
354     A: Allocator,
356     type Borrowed<'a> = &'a T;
357     type BorrowedMut<'a> = &'a mut T;
359     fn into_foreign(self) -> *mut crate::ffi::c_void {  in into_foreign()
363     unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {  in from_foreign()
364         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
369     unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> &'a T {  in borrow()
371         // immutable for the duration of 'a.  in borrow()
375     unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> &'a mut T {  in borrow_mut()
378         // nothing else will access the value for the duration of 'a.  in borrow_mut()
383 impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
385     A: Allocator,
387     type Borrowed<'a> = Pin<&'a T>;
388     type BorrowedMut<'a> = Pin<&'a mut T>;
390     fn into_foreign(self) -> *mut crate::ffi::c_void {  in into_foreign()
395     unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {  in from_foreign()
396         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
401     unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a T> {  in borrow()
408         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow()
412     unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a mut T> {  in borrow_mut()
420         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow_mut()
425 impl<T, A> Deref for Box<T, A>
428     A: Allocator,
432     fn deref(&self) -> &T {  in deref()
439 impl<T, A> DerefMut for Box<T, A>
442     A: Allocator,
444     fn deref_mut(&mut self) -> &mut T {  in deref_mut()
451 impl<T, A> fmt::Display for Box<T, A>
454     A: Allocator,
456     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
461 impl<T, A> fmt::Debug for Box<T, A>
464     A: Allocator,
466     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
471 impl<T, A> Drop for Box<T, A>
474     A: Allocator,
483         // - `self.0` was previously allocated with `A`.  in drop()
484         // - `layout` is equal to the `Layout´ `self.0` was allocated with.  in drop()
485         unsafe { A::free(self.0.cast(), layout) };  in drop()