Struct UniqueArc

pub struct UniqueArc<T: ?Sized> { /* private fields */ }

A refcounted object that is known to have a refcount of 1.

It is mutable and can be converted to an Arc so that it can be shared.

Invariants

inner always has a reference count of 1.

Examples

In the following example, we make changes to the inner object before turning it into an Arc<Test> object (after which point, it cannot be mutated directly). Note that x.into() cannot fail.

use kernel::sync::{Arc, UniqueArc};

struct Example {
    a: u32,
    b: u32,
}

fn test() -> Result<Arc<Example>> {
    let mut x = UniqueArc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
    x.a += 1;
    x.b += 1;
    Ok(x.into())
}

In the following example we first allocate memory for a refcounted Example but we don’t initialise it on allocation. We do initialise it later with a call to UniqueArc::write, followed by a conversion to Arc<Example>. This is particularly useful when allocation happens in one context (e.g., sleepable) and initialisation in another (e.g., atomic):

use kernel::sync::{Arc, UniqueArc};

struct Example {
    a: u32,
    b: u32,
}

fn test() -> Result<Arc<Example>> {
    let x = UniqueArc::new_uninit(GFP_KERNEL)?;
    Ok(x.write(Example { a: 10, b: 20 }).into())
}

In the last example below, the caller gets a pinned instance of Example while converting to Arc<Example>; this is useful in scenarios where one needs a pinned reference during initialisation, for example, when initialising fields that are wrapped in locks.

use kernel::sync::{Arc, UniqueArc};

struct Example {
    a: u32,
    b: u32,
}

fn test() -> Result<Arc<Example>> {
    let mut pinned = Pin::from(UniqueArc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?);
    // We can modify `pinned` because it is `Unpin`.
    pinned.as_mut().a += 1;
    Ok(pinned.into())
}

Implementations

impl<T> UniqueArc<T>

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

Tries to allocate a new UniqueArc instance.

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

Tries to allocate a new UniqueArc instance whose contents are not initialised yet.

impl<T> UniqueArc<MaybeUninit<T>>

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

Converts a UniqueArc<MaybeUninit<T>> into a UniqueArc<T> by writing a value into it.

pub unsafe fn assume_init(self) -> UniqueArc<T>

Unsafely assume that self is initialized.

Safety

The caller guarantees that the value behind this pointer has been initialized. It is immediate UB to call this when the value is not initialized.

pub fn init_with<E>(self, init: impl Init<T, E>) -> Result<UniqueArc<T>, E>

Initialize self using the given initializer.

pub fn pin_init_with<E>( self, init: impl PinInit<T, E>, ) -> Result<Pin<UniqueArc<T>>, E>

Pin-initialize self using the given pin-initializer.

Trait Implementations

impl<T: Debug + ?Sized> Debug for UniqueArc<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for UniqueArc<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ?Sized> DerefMut for UniqueArc<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: Display + ?Sized> Display for UniqueArc<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> From<UniqueArc<T>> for Arc<T>

fn from(item: UniqueArc<T>) -> Self

Converts to this type from the input type.

impl<T, const ID: u64> From<UniqueArc<T>> for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

fn from(unique: UniqueArc<T>) -> Self

Convert a UniqueArc into a ListArc.

impl<T: ?Sized> From<UniqueArc<T>> for Pin<UniqueArc<T>>

fn from(obj: UniqueArc<T>) -> Self

Converts to this type from the input type.

impl<T> InPlaceInit<T> for UniqueArc<T>

type PinnedSelf = Pin<UniqueArc<T>>

Pinned version of Self.

fn try_pin_init<E>( init: impl PinInit<T, E>, flags: Flags, ) -> Result<Self::PinnedSelf, 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> InPlaceWrite<T> for UniqueArc<MaybeUninit<T>>

type Initialized = UniqueArc<T>

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.