Struct kernel::sync::Arc

source ·

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

Expand description

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§

source §

impl Arc<dyn Any + Send + Sync>

source

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.

source §

impl<T> Arc<T>

source

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

Constructs a new reference counted instance of T.

source

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.

source

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 Arc<T>::pin_init, since an Arc is always pinned.

source §

impl<T: ?Sized> Arc<T>

source

pub fn into_raw(self) -> *const T

Convert the Arc into a raw pointer.

The raw pointer has ownership of the refcount that this Arc object owned.

source

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

Recreates an Arc instance previously deconstructed via Arc::into_raw.

Safety

ptr must have been returned by a previous call to Arc::into_raw. Additionally, it must not be called more than once for each previous call to Arc::into_raw.

source

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.

source