Struct Arc

Help

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 refcounted instance of `Example`.
let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;

// 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::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
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::new(Example, GFP_KERNEL)?;

// `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 new(contents: T, flags: Flags) -> Result<Self, AllocError>

Constructs a new reference counted instance of T.

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

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Compare whether two Arc pointers reference the same underlying object.

Source

pub fn into_unique_or_drop(self) -> Option<Pin<UniqueArc<T>>>

Converts this Arc into a UniqueArc, or destroys it if it is not unique.

When this destroys the Arc, it does so while properly avoiding races. This means that this method will never call the destructor of the value.

§Examples

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

let arc = Arc::new(42, GFP_KERNEL)?;
let unique_arc = arc.into_unique_or_drop();

// The above conversion should succeed since refcount of `arc` is 1.
assert!(unique_arc.is_some());

assert_eq!(*(unique_arc.unwrap()), 42);

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

let arc = Arc::new(42, GFP_KERNEL)?;
let another = arc.clone();

let unique_arc = arc.into_unique_or_drop();

// The above conversion should fail since refcount of `arc` is >1.
assert!(unique_arc.is_none());