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<T> Arc<T>

source

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

Constructs a new reference counted instance of T.

source

impl<T: ?Sized> Arc<T>

source

pub fn ptr_eq(a: &Self, b: &Self) -> bool

Determines if two reference-counted pointers point to the same underlying instance of T.

source

pub fn into_raw(obj: Self) -> *const T

Deconstructs a Arc object into a raw pointer.

It can be reconstructed once via Arc::from_raw.

source

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

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

This code relies on the repr(C) layout of structs as described in https://doc.rust-lang.org/reference/type-layout.html#reprc-structs.

Safety

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

source

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

Returns a ArcBorrow from the given Arc.

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