25 /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
28 /// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
36 /// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
77 /// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
78 /// zero-sized types, is a dangling, well aligned pointer.
81 pub struct Box<#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, pointee)] T: ?Sized, A: Allocator>(
83     PhantomData<A>,
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>
93     A: Allocator,
97 // This is to allow `Box<U, A>` to be dispatched on when `Box<T, A>` can be coerced into `Box<U,
98 // A>`.
100 impl<T, U, A> core::ops::DispatchFromDyn<Box<U, A>> for Box<T, A>
104     A: Allocator,
108 /// Type alias for [`Box`] with a [`Kmalloc`] allocator.
120 /// Type alias for [`Box`] with a [`Vmalloc`] allocator.
132 /// Type alias for [`Box`] with a [`KVmalloc`] allocator.
146 unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {}
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>
152     A: Allocator,
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>
160     A: Allocator,
164 impl<T, A> Box<T, A>
167     A: Allocator,
169     /// Creates a new `Box<T, A>` from a raw pointer.
173     /// For non-ZSTs, `raw` must point at an allocation allocated with `A` that is sufficiently
174     /// aligned for and holds a valid `T`. The caller passes ownership of the allocation to the
177     /// For ZSTs, `raw` must be a dangling, well aligned pointer.
181         // SAFETY: By the safety preconditions of this function, `raw` is not a NULL pointer.  in from_raw()
185     /// Consumes the `Box<T, A>` and returns a raw pointer.
196     /// // SAFETY: `ptr` comes from a previous call to `KBox::into_raw`.
207     /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
211     pub fn leak<'a>(b: Self) -> &'a mut T {  in leak()
212         // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer  in leak()
218 impl<T, A> Box<MaybeUninit<T>, A>
220     A: Allocator,
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()  argument
233         // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements  in assume_init()
235         // safe to reconstruct the `Box` as `Box<T, A>`.  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()  argument
248 impl<T, A> Box<T, A>
250     A: Allocator,
252     /// Creates a new `Box<T, A>` and initializes its contents with `x`.
254     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
261     /// Creates a new `Box<T, A>` with uninitialized contents.
263     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
275     pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {  in new_uninit()  argument
277         let ptr = A::alloc(layout, flags, NumaNode::NO_NODE)?;  in new_uninit()
279         // INVARIANT: `ptr` is either a dangling pointer or points to memory allocated with `A`,  in new_uninit()
280         // which is sufficient in size and alignment for storing a `T`.  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()  argument
289         A: 'static,  in pin()
294     /// Construct a pinned slice of elements `Pin<Box<[T], A>>`.
296     /// This is a convenient means for creation of e.g. slices of structrures containing spinlocks
305     ///     a: u32,
320     ///             d <- new_spinlock!(Inner { a: 20, b: 30 }),
325     /// // Allocate a boxed slice of 10 `Example`s.
333     /// assert_eq!(s[3].d.lock().a, 20);
340     ) -> Result<Pin<Box<[T], A>>, E>  in pin_slice()  argument
346         let mut buffer = super::Vec::<T, A>::with_capacity(len, flags)?;  in pin_slice()
350             // - `ptr` is a valid pointer to uninitialized memory.  in pin_slice()
366         // SAFETY: `slice` points to an allocation allocated with `A` (`buffer`) and holds a valid  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()  argument
398     pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in drop_contents()  argument
417 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
420     A: Allocator,
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>
435     A: Allocator + 'static,
437     type Initialized = Box<T, A>;
458 impl<T, A> InPlaceInit<T> for Box<T, A>
460     A: Allocator + 'static,
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()
481 // SAFETY: The pointer returned by `into_foreign` comes from a well aligned
482 // pointer to `T` allocated by `A`.
483 unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A>
485     A: Allocator,
487     const FOREIGN_ALIGN: usize = if core::mem::align_of::<T>() < A::MIN_ALIGN {
488         A::MIN_ALIGN
493     type Borrowed<'a> = &'a T;
494     type BorrowedMut<'a> = &'a mut T;
501         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
506     unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T {  in borrow()
508         // immutable for the duration of 'a.  in borrow()
512     unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a mut T {  in borrow_mut()
515         // nothing else will access the value for the duration of 'a.  in borrow_mut()
520 // SAFETY: The pointer returned by `into_foreign` comes from a well aligned
521 // pointer to `T` allocated by `A`.
522 unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
524     A: Allocator,
526     const FOREIGN_ALIGN: usize = <Box<T, A> as ForeignOwnable>::FOREIGN_ALIGN;
527     type Borrowed<'a> = Pin<&'a T>;
528     type BorrowedMut<'a> = Pin<&'a mut T>;
536         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
541     unsafe fn borrow<'a>(ptr: *mut c_void) -> Pin<&'a T> {  in borrow()
548         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow()
552     unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Pin<&'a mut T> {  in borrow_mut()
560         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow_mut()
565 impl<T, A> Deref for Box<T, A>
568     A: Allocator,
579 impl<T, A> DerefMut for Box<T, A>
582     A: Allocator,
609 impl<T, A> Borrow<T> for Box<T, A>
612     A: Allocator,
637 impl<T, A> BorrowMut<T> for Box<T, A>
640     A: Allocator,
647 impl<T, A> fmt::Display for Box<T, A>
650     A: Allocator,
657 impl<T, A> fmt::Debug for Box<T, A>
660     A: Allocator,
667 impl<T, A> Drop for Box<T, A>
670     A: Allocator,
679         // - `self.0` was previously allocated with `A`.  in drop()
681         unsafe { A::free(self.0.cast(), layout) };  in drop()
705     type Iter<'a>
706         = VmallocPageIter<'a>
708         T: 'a;
715         // - `ptr` is a valid pointer to the beginning of a `Vmalloc` allocation.  in page_iter()
716         // - `ptr` is guaranteed to be valid for the lifetime of `'a`.  in page_iter()