Struct Box

pub struct Box<T: ?Sized, A: Allocator>(/* private fields */);

The kernel’s Box type – a heap allocation for a single value of type T.

This is the kernel’s version of the Rust stdlib’s Box. There are several differences, for example no noalias attribute is emitted and partially moving out of a Box is not supported. There are also several API differences, e.g. Box always requires an Allocator implementation to be passed as generic, page Flags when allocating memory and all functions that may allocate memory are fallible.

Box works with any of the kernel’s allocators, e.g. Kmalloc, Vmalloc or KVmalloc. There are aliases for Box with these allocators (KBox, VBox, KVBox).

When dropping a Box, the value is also dropped and the heap memory is automatically freed.

Examples

let b = KBox::<u64>::new(24_u64, GFP_KERNEL)?;

assert_eq!(*b, 24_u64);

const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
struct Huge([u8; SIZE]);

assert!(KBox::<Huge>::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err());

const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
struct Huge([u8; SIZE]);

assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok());

Invariants

self.0 is always properly aligned and either points to memory allocated with A or, for zero-sized types, is a dangling, well aligned pointer.

Implementations

impl<T, A> Box<T, A>

where T: ?Sized, A: Allocator,

pub const unsafe fn from_raw(raw: *mut T) -> Self

Creates a new Box<T, A> from a raw pointer.

Safety

For non-ZSTs, raw must point at an allocation allocated with A that is sufficiently aligned for and holds a valid T. The caller passes ownership of the allocation to the Box.

For ZSTs, raw must be a dangling, well aligned pointer.

pub fn into_raw(b: Self) -> *mut T

Consumes the Box<T, A> and returns a raw pointer.

This will not run the destructor of T and for non-ZSTs the allocation will stay alive indefinitely. Use Box::from_raw to recover the Box, drop the value and free the allocation, if any.

Examples

let x = KBox::new(24, GFP_KERNEL)?;
let ptr = KBox::into_raw(x);
// SAFETY: `ptr` comes from a previous call to `KBox::into_raw`.
let x = unsafe { KBox::from_raw(ptr) };

assert_eq!(*x, 24);

pub fn leak<'a>(b: Self) -> &'a mut T

Consumes and leaks the Box<T, A> and returns a mutable reference.

See Box::into_raw for more details.

impl<T, A> Box<MaybeUninit<T>, A>

where A: Allocator,

pub unsafe fn assume_init(self) -> Box<T, A>

Converts a Box<MaybeUninit<T>, A> to a Box<T, A>.

It is undefined behavior to call this function while the value inside of b is not yet fully initialized.

Safety

Callers must ensure that the value inside of b is in an initialized state.

pub fn write(self, value: T) -> Box<T, A>

Writes the value and converts to Box<T, A>.

impl<T, A> Box<T, A>

where A: Allocator,

pub fn new(x: T, flags: Flags) -> Result<Self, AllocError>

Creates a new Box<T, A> and initializes its contents with x.

New memory is allocated with A. The allocation may fail, in which case an error is returned. For ZSTs no memory is allocated.

pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError>

Creates a new Box<T, A> with uninitialized contents.

New memory is allocated with A. The allocation may fail, in which case an error is returned. For ZSTs no memory is allocated.

Examples

let b = KBox::<u64>::new_uninit(GFP_KERNEL)?;
let b = KBox::write(b, 24);

assert_eq!(*b, 24_u64);

pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>

where A: 'static,

Constructs a new Pin<Box<T, A>>. If T does not implement Unpin, then x will be pinned in memory and can’t be moved.

pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A>

Drops the contents, but keeps the allocation.

Examples

let value = KBox::new([0; 32], GFP_KERNEL)?;
assert_eq!(*value, [0; 32]);
let value = KBox::drop_contents(value);
// Now we can re-use `value`:
let value = KBox::write(value, [1; 32]);
assert_eq!(*value, [1; 32]);

pub fn into_inner(b: Self) -> T

Moves the Box’s value out of the Box and consumes the Box.

Trait Implementations

impl<T, A> Debug for Box<T, A>

where T: ?Sized + Debug, A: Allocator,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, A> Deref for Box<T, A>

where T: ?Sized, A: Allocator,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T, A> DerefMut for Box<T, A>

where T: ?Sized, A: Allocator,

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T, A> Drop for Box<T, A>

where T: ?Sized, A: Allocator,

fn drop(&mut self)

Executes the destructor for this type.

impl<T: 'static, A> ForeignOwnable for Box<T, A>

where A: Allocator,

type Borrowed<'a> = &'a T

Type of values borrowed between calls to ForeignOwnable::into_foreign and ForeignOwnable::from_foreign.

fn into_foreign(self) -> *const c_void

Converts a Rust-owned object to a foreign-owned one.

unsafe fn from_foreign(ptr: *const c_void) -> Self

Converts a foreign-owned object back to a Rust-owned one.

unsafe fn borrow<'a>(ptr: *const c_void) -> &'a T

Borrows a foreign-owned object.

unsafe fn try_from_foreign(ptr: *const c_void) -> Option<Self>

Tries to convert a foreign-owned object back to a Rust-owned one.

impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>

where A: Allocator,

type Borrowed<'a> = Pin<&'a T>

Type of values borrowed between calls to ForeignOwnable::into_foreign and ForeignOwnable::from_foreign.

fn into_foreign(self) -> *const c_void

Converts a Rust-owned object to a foreign-owned one.

unsafe fn from_foreign(ptr: *const c_void) -> Self

Converts a foreign-owned object back to a Rust-owned one.

unsafe fn borrow<'a>(ptr: *const c_void) -> Pin<&'a T>

Borrows a foreign-owned object.

unsafe fn try_from_foreign(ptr: *const c_void) -> Option<Self>

Tries to convert a foreign-owned object back to a Rust-owned one.

impl<T, A, const N: usize> From<Box<[T; N], A>> for Vec<T, A>

where A: Allocator,

fn from(b: Box<[T; N], A>) -> Vec<T, A>

Converts to this type from the input type.

impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>

where T: ?Sized, A: Allocator,

fn from(b: Box<T, A>) -> Self

Converts a Box<T, A> into a Pin<Box<T, A>>. If T does not implement Unpin, then *b will be pinned in memory and can’t be moved.

This moves b into Pin without moving *b or allocating and copying any memory.

impl<T, A> InPlaceInit<T> for Box<T, A>

where A: Allocator + 'static,

type PinnedSelf = Pin<Box<T, A>>

Pinned version of Self.

fn try_pin_init<E>( init: impl PinInit<T, E>, flags: Flags, ) -> Result<Pin<Self>, E>

where E: From<AllocError>,

Use the given pin-initializer to pin-initialize a T inside of a new smart pointer of this type.

fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>

where E: From<AllocError>,

Use the given initializer to in-place initialize a T.

fn pin_init<E>( init: impl PinInit<T, E>, flags: Flags, ) -> Result<Self::PinnedSelf>

where Error: From<E>,

Use the given pin-initializer to pin-initialize a T inside of a new smart pointer of this type.

fn init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self>

where Error: From<E>,

Use the given initializer to in-place initialize a T.

impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>

where A: Allocator + 'static,

type Initialized = Box<T, A>

The type Self turns into when the contents are initialized.

fn write_init<E>(self, init: impl Init<T, E>) -> Result<Self::Initialized, E>

Use the given initializer to write a value into self.

fn write_pin_init<E>( self, init: impl PinInit<T, E>, ) -> Result<Pin<Self::Initialized>, E>

Use the given pin-initializer to write a value into self.

impl<T, A> Send for Box<T, A>

where T: Send + ?Sized, A: Allocator,

impl<T, A> Sync for Box<T, A>

where T: Sync + ?Sized, A: Allocator,