3 //! Implementation of [`Box`].
21 /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
23 /// This is the kernel's version of the Rust stdlib's `Box`. There are several differences,
24 /// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
25 /// supported. There are also several API differences, e.g. `Box` always requires an [`Allocator`]
29 /// `Box` works with any of the kernel's allocators, e.g. [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`].
30 /// There are aliases for `Box` with these allocators ([`KBox`], [`VBox`], [`KVBox`]).
32 /// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
64 pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);  struct
66 /// Type alias for [`Box`] with a [`Kmalloc`] allocator.
76 pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
78 /// Type alias for [`Box`] with a [`Vmalloc`] allocator.
88 pub type VBox<T> = Box<T, super::allocator::Vmalloc>;
90 /// Type alias for [`Box`] with a [`KVmalloc`] allocator.
100 pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
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>  implementation
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>  implementation
118 impl<T, A> Box<T, A>  impl
123     /// Creates a new `Box<T, A>` from a raw pointer.
129     /// `Box`.
139     /// Consumes the `Box<T, A>` and returns a raw pointer.
142     /// indefinitely. Use [`Box::from_raw`] to recover the [`Box`], drop the value and free the
161     /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
163     /// See [`Box::into_raw`] for more details.
166         // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer  in leak()
168         unsafe { &mut *Box::into_raw(b) }  in leak()
172 impl<T, A> Box<MaybeUninit<T>, A>  impl
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()
187         // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements  in assume_init()
188         // of this function, the value inside the `Box` is in an initialized state. Hence, it is  in assume_init()
189         // safe to reconstruct the `Box` as `Box<T, A>`.  in assume_init()
190         unsafe { Box::from_raw(raw.cast()) }  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()
202 impl<T, A> Box<T, A>  impl
206     /// Creates a new `Box<T, A>` and initializes its contents with `x`.
212         Ok(Box::write(b, x))  in new()
215     /// Creates a new `Box<T, A>` with uninitialized contents.
229     pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {  in new_uninit()
235         Ok(Box(ptr.cast(), PhantomData))  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()
249     fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in forget_contents()
252         // SAFETY: `ptr` is valid, because it came from `Box::into_raw`.  in forget_contents()
253         unsafe { Box::from_raw(ptr.cast()) }  in forget_contents()
269     pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {  in drop_contents()
279     /// Moves the `Box`'s value out of the `Box` and consumes the `Box`.
288 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
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>  implementation
308     type Initialized = Box<T, A>;
316         Ok(unsafe { Box::assume_init(self) })  in write_init()
325         Ok(unsafe { Box::assume_init(self) }.into())  in write_pin_init()
329 impl<T, A> InPlaceInit<T> for Box<T, A>  implementation
340         Box::<_, A>::new_uninit(flags)?.write_pin_init(init)  in try_pin_init()
348         Box::<_, A>::new_uninit(flags)?.write_init(init)  in try_init()
352 impl<T: 'static, A> ForeignOwnable for Box<T, A>  implementation
360         Box::into_raw(self).cast()  in into_foreign()
366         unsafe { Box::from_raw(ptr.cast()) }  in from_foreign()
383 impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
391         // SAFETY: We are still treating the box as pinned.  in into_foreign()
392         Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()  in into_foreign()
398         unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }  in from_foreign()
408         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow()
420         // SAFETY: This pointer originates from a `Pin<Box<T>>`.  in borrow_mut()
425 impl<T, A> Deref for Box<T, A>  implementation
439 impl<T, A> DerefMut for Box<T, A>  implementation
451 impl<T, A> fmt::Display for Box<T, A>  implementation
461 impl<T, A> fmt::Debug for Box<T, A>  implementation
471 impl<T, A> Drop for Box<T, A>  implementation