Struct kernel::sync::Arc

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

A reference-counted pointer to an instance of T.

The reference count is incremented when new instances of Arc are created, and decremented when they are dropped. When the count reaches zero, the underlying T is also dropped.

Invariants

The reference count on an instance of Arc is always non-zero. The object pointed to by Arc is always pinned.

Examples

use kernel::sync::Arc;

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

// Create a ref-counted instance of `Example`.
let obj = Arc::try_new(Example { a: 10, b: 20 })?;

// Get a new pointer to `obj` and increment the refcount.
let cloned = obj.clone();

// Assert that both `obj` and `cloned` point to the same underlying object.
assert!(core::ptr::eq(&*obj, &*cloned));

// Destroy `obj` and decrement its refcount.
drop(obj);

// Check that the values are still accessible through `cloned`.
assert_eq!(cloned.a, 10);
assert_eq!(cloned.b, 20);

// The refcount drops to zero when `cloned` goes out of scope, and the memory is freed.

Using Arc<T> as the type of self:

use kernel::sync::Arc;

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

impl Example {
    fn take_over(self: Arc<Self>) {
        // ...
    }

    fn use_reference(self: &Arc<Self>) {
        // ...
    }
}

let obj = Arc::try_new(Example { a: 10, b: 20 })?;
obj.use_reference();
obj.take_over();

Coercion from Arc<Example> to Arc<dyn MyTrait>:

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

trait MyTrait {
    // Trait has a function whose `self` type is `Arc<Self>`.
    fn example1(self: Arc<Self>) {}

    // Trait has a function whose `self` type is `ArcBorrow<'_, Self>`.
    fn example2(self: ArcBorrow<'_, Self>) {}
}

struct Example;
impl MyTrait for Example {}

// `obj` has type `Arc<Example>`.
let obj: Arc<Example> = Arc::try_new(Example)?;

// `coerced` has type `Arc<dyn MyTrait>`.
let coerced: Arc<dyn MyTrait> = obj;

Implementations

impl Arc<dyn Any + Send + Sync>

pub fn downcast<T>(self) -> Result<Arc<T>, Self> where
    T: Any + Send + Sync, 

Attempt to downcast the Arc<dyn Any + Send + Sync> to a concrete type.

impl<T> Arc<T>

pub fn try_new(contents: T) -> Result<Self, AllocError>

Constructs a new reference counted instance of T.

pub fn pin_init<E>(init: impl PinInit<T, E>) -> Result<Self> where
    Error: From<E>, 

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

If T: !Unpin it will not be able to move afterwards.

pub fn init<E>(init: impl Init<T, E>) -> Result<Self> where
    Error: From<E>, 

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

This is equivalent to pin_init, since an Arc is always pinned.

impl<T: ?Sized> Arc<T>

pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T>

Returns an ArcBorrow from the given Arc.

This is useful when the argument of a function call is an ArcBorrow (e.g., in a method receiver), but we have an Arc instead. Getting an ArcBorrow is free when optimised.

Trait Implementations

impl<T: ?Sized> Clone for Arc<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

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

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

Formats the value using the given formatter.

impl<T: ?Sized> Drop for Arc<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: 'static> ForeignOwnable for Arc<T>

type Borrowed<'a> = ArcBorrow<'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 borrow<'a>(ptr: *const c_void) -> ArcBorrow<'a, T>

Borrows a foreign-owned object.

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

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

unsafe fn borrow_mut(ptr: *const c_void) -> ScopeGuard<Self, fn(_: Self)>

Mutably borrows a foreign-owned object.

impl<T: ?Sized> From<ArcBorrow<'_, T>> for Arc<T>

fn from(b: ArcBorrow<'_, T>) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Arc<U>> for Arc<T>

impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Arc<U>> for Arc<T>

impl<T: ?Sized + Sync + Send> Send for Arc<T>

impl<T: ?Sized + Sync + Send> Sync for Arc<T>