3 //! Implementation of [`Box`].
25 /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
27 /// This is the kernel's version of the Rust stdlib's `Box`. There are several differences,
28 /// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
29 /// supported. There are also several API differences, e.g. `Box` always requires an [`Allocator`]
33 /// `Box` works with any of the kernel's allocators, e.g. [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`].
34 /// There are aliases for `Box` with these allocators ([`KBox`], [`VBox`], [`KVBox`]).
36 /// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
63 /// [`Box`]es can also be used to store trait objects by coercing their type:
81 pub struct Box<#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, pointee)] T: ?Sized, A: Allocator>(  struct
86 // This is to allow coercion from `Box<T, A>` to `Box<U, A>` if `T` can be converted to the
89 impl<T, U, A> core::ops::CoerceUnsized<Box<U, A>> for Box<T, A>  implementation
97 // This is to allow `Box<U, A>` to be dispatched on when `Box<T, A>` can be coerced into `Box<U,
100 impl<T, U, A> core::ops::DispatchFromDyn<Box<U, A>> for Box<T, A>  implementation
108 /// Type alias for [`Box`] with a [`Kmalloc`] allocator.
118 pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
120 /// Type alias for [`Box`] with a [`Vmalloc`] allocator.
130 pub type VBox<T> = Box<T, super::allocator::Vmalloc>;
132 /// Type alias for [`Box`] with a [`KVmalloc`] allocator.
142 pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
146 unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {}  implementation
148 // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
149 unsafe impl<T, A> Send for Box<T, A>  implementation
156 // SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`.
157 unsafe impl<T, A> Sync for Box<T, A>  implementation
164 impl<T, A> Box<T, A>  impl
169     /// Creates a new `Box<T, A>` from a raw pointer.
175     /// `Box`.
185     /// Consumes the `Box<T, A>` and returns a raw pointer.
188     /// indefinitely. Use [`Box::from_raw`] to recover the [`Box`], drop the value and free the
207     /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
209     /// See [`Box::into_raw`] for more details.
212         // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer  in leak()
214         unsafe { &mut *Box::into_raw(b) }  in leak()
218 impl<T, A> Box<MaybeUninit<T>, A>  impl
222     /// Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`.
230     pub unsafe fn assume_init(self) -> Box<T, A> {  in assume_init()
233         // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements  in assume_init()
234         // of this function, the value inside the `Box` is in an initialized state. Hence, it is  in assume_init()
235         // safe to reconstruct the `Box` as `Box<T, A>`.  in assume_init()
236         unsafe { Box::from_raw(raw.cast()) }  in assume_init()
239     /// Writes the value and converts to `Box<T, A>`.
240     pub fn write(mut self, value: T) -> Box<T, A> {  in write()
248 impl<T, A> Box<T, A>  implementation
252     /// Creates a new `Box<T, A>` and initializes its contents with `x`.
258         Ok(Box::write(b, x))  in new()
261     /// Creates a new `Box<T, A>` with uninitialized contents.
275     pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {  in new_uninit()
281         Ok(Box(ptr.cast(), PhantomData))  in new_uninit()
284     /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be
287     pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>  in pin()
294     /// Construct a pinned slice of elements `Pin<Box<[T], A>>`.
340     ) -> Result<Pin<Box<[T], A>>, E>  in pin_slice()
368         Ok(Pin::from(unsafe { Box::from_raw(slice) }))  in pin_slice()
371     /// Convert a [`Box<T,A>`] to a [`Pin<Box<T,A>>`]. If `T` does not implement
378     fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in forget_contents()
381         // SAFETY: `ptr` is valid, because it came from `Box::into_raw`.  in forget_contents()
382         unsafe { Box::from_raw(ptr.cast()) }  in forget_contents()
398     pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in drop_contents()
408     /// Moves the `Box`'s value out of the `Box` and consumes the `Box`.
417 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
422     /// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
426     fn from(b: Box<T, A>) -> Self {  in from()
427         // SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long  in from()
433 impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>  implementation
437     type Initialized = Box<T, A>;
445         Ok(unsafe { Box::assume_init(self) })  in write_init()
454         Ok(unsafe { Box::assume_init(self) }.into())  in write_pin_init()
458 impl<T, A> InPlaceInit<T> for Box<T, A>  implementation
469         Box::<_, A>::new_uninit(flags)?.write_pin_init(init)  in try_pin_init()
477         Box::<_, A>::new_uninit(flags)?.write_init(init)  in try_init()
483 unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A>  implementation
497         Box::into_raw(self).cast()  in into_foreign()
503         unsafe { Box::from_raw(ptr.cast()) }  in from_foreign()
522 unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
526     const FOREIGN_ALIGN: usize = <Box<T, A> as ForeignOwnable>::FOREIGN_ALIGN;
531         // SAFETY: We are still treating the box as pinned.  in into_foreign()
532         Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()  in into_foreign()
538         unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }  in from_foreign()
548         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow()
560         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow_mut()
565 impl<T, A> Deref for Box<T, A>  implementation
579 impl<T, A> DerefMut for Box<T, A>  implementation
609 impl<T, A> Borrow<T> for Box<T, A>  implementation
637 impl<T, A> BorrowMut<T> for Box<T, A>  implementation
647 impl<T, A> fmt::Display for Box<T, A>  implementation
657 impl<T, A> fmt::Debug for Box<T, A>  implementation
667 impl<T, A> Drop for Box<T, A>  implementation