24 /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
27 /// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
35 /// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
76 /// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
77 /// zero-sized types, is a dangling, well aligned pointer.
80 pub struct Box<#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, pointee)] T: ?Sized, A: Allocator>(
82     PhantomData<A>,
85 // This is to allow coercion from `Box<T, A>` to `Box<U, A>` if `T` can be converted to the
88 impl<T, U, A> core::ops::CoerceUnsized<Box<U, A>> for Box<T, A>
92     A: Allocator,
96 // This is to allow `Box<U, A>` to be dispatched on when `Box<T, A>` can be coerced into `Box<U,
97 // A>`.
99 impl<T, U, A> core::ops::DispatchFromDyn<Box<U, A>> for Box<T, A>
103     A: Allocator,
107 /// Type alias for [`Box`] with a [`Kmalloc`] allocator.
119 /// Type alias for [`Box`] with a [`Vmalloc`] allocator.
131 /// Type alias for [`Box`] with a [`KVmalloc`] allocator.
145 unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {}
147 // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
148 unsafe impl<T, A> Send for Box<T, A>
151     A: Allocator,
155 // SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`.
156 unsafe impl<T, A> Sync for Box<T, A>
159     A: Allocator,
163 impl<T, A> Box<T, A>
166     A: Allocator,
168     /// Creates a new `Box<T, A>` from a raw pointer.
172     /// For non-ZSTs, `raw` must point at an allocation allocated with `A` that is sufficiently
173     /// aligned for and holds a valid `T`. The caller passes ownership of the allocation to the
176     /// For ZSTs, `raw` must be a dangling, well aligned pointer.
180         // SAFETY: By the safety preconditions of this function, `raw` is not a NULL pointer.  in from_raw()
184     /// Consumes the `Box<T, A>` and returns a raw pointer.
195     /// // SAFETY: `ptr` comes from a previous call to `KBox::into_raw`.
206     /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
210     pub fn leak<'a>(b: Self) -> &'a mut T {  in leak()
211         // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer  in leak()
217 impl<T, A> Box<MaybeUninit<T>, A>
219     A: Allocator,
221     /// Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`.
229     pub unsafe fn assume_init(self) -> Box<T, A> {  in assume_init()  argument
232         // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements  in assume_init()
234         // safe to reconstruct the `Box` as `Box<T, A>`.  in assume_init()
238     /// Writes the value and converts to `Box<T, A>`.
239     pub fn write(mut self, value: T) -> Box<T, A> {  in write()  argument
247 impl<T, A> Box<T, A>
249     A: Allocator,
251     /// Creates a new `Box<T, A>` and initializes its contents with `x`.
253     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
260     /// Creates a new `Box<T, A>` with uninitialized contents.
262     /// New memory is allocated with `A`. The allocation may fail, in which case an error is
274     pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {  in new_uninit()  argument
276         let ptr = A::alloc(layout, flags)?;  in new_uninit()
278         // INVARIANT: `ptr` is either a dangling pointer or points to memory allocated with `A`,  in new_uninit()
279         // which is sufficient in size and alignment for storing a `T`.  in new_uninit()
283     /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be
286     pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>  in pin()  argument
288         A: 'static,  in pin()
293     /// Convert a [`Box<T,A>`] to a [`Pin<Box<T,A>>`]. If `T` does not implement
300     fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in forget_contents()  argument
320     pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in drop_contents()  argument
339 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
342     A: Allocator,
344     /// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
348     fn from(b: Box<T, A>) -> Self {  in from()
349         // SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long  in from()
355 impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>
357     A: Allocator + 'static,
359     type Initialized = Box<T, A>;
380 impl<T, A> InPlaceInit<T> for Box<T, A>
382     A: Allocator + 'static,
391         Box::<_, A>::new_uninit(flags)?.write_pin_init(init)  in try_pin_init()
399         Box::<_, A>::new_uninit(flags)?.write_init(init)  in try_init()
403 // SAFETY: The pointer returned by `into_foreign` comes from a well aligned
405 unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A>
407     A: Allocator,
410     type Borrowed<'a> = &'a T;
411     type BorrowedMut<'a> = &'a mut T;
418         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
423     unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T {  in borrow()
425         // immutable for the duration of 'a.  in borrow()
429     unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a mut T {  in borrow_mut()
432         // nothing else will access the value for the duration of 'a.  in borrow_mut()
437 // SAFETY: The pointer returned by `into_foreign` comes from a well aligned
439 unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
441     A: Allocator,
444     type Borrowed<'a> = Pin<&'a T>;
445     type BorrowedMut<'a> = Pin<&'a mut T>;
453         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous  in from_foreign()
458     unsafe fn borrow<'a>(ptr: *mut c_void) -> Pin<&'a T> {  in borrow()
465         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow()
469     unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Pin<&'a mut T> {  in borrow_mut()
477         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow_mut()
482 impl<T, A> Deref for Box<T, A>
485     A: Allocator,
496 impl<T, A> DerefMut for Box<T, A>
499     A: Allocator,
526 impl<T, A> Borrow<T> for Box<T, A>
529     A: Allocator,
554 impl<T, A> BorrowMut<T> for Box<T, A>
557     A: Allocator,
564 impl<T, A> fmt::Display for Box<T, A>
567     A: Allocator,
574 impl<T, A> fmt::Debug for Box<T, A>
577     A: Allocator,
584 impl<T, A> Drop for Box<T, A>
587     A: Allocator,
596         // - `self.0` was previously allocated with `A`.  in drop()
598         unsafe { A::free(self.0.cast(), layout) };  in drop()