Struct Arc

source

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

Expand description

An atomically reference counted shared pointer

See the documentation for Arc in the standard library. Unlike the standard library Arc, this Arc does not support weak reference counting.

Implementations§

source §

impl<T> Arc<T>

source

pub fn new(data: T) -> Self

Construct an Arc<T>

source

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

Reconstruct the Arc<T> from a raw pointer obtained from into_raw()

Note: This raw pointer will be offset in the allocation and must be preceded by the atomic count.

It is recommended to use OffsetArc for this

§Safety

The given pointer must be a valid pointer to T that came from Arc::into_raw.
After from_raw, the pointer must not be accessed.

source

pub fn with_raw_offset_arc<F, U>(&self, f: F) -> U
where F: FnOnce(&OffsetArc<T>) -> U,

Temporarily converts |self| into a bonafide OffsetArc and exposes it to the provided callback. The refcount is not modified.

source

pub fn into_raw_offset(a: Self) -> OffsetArc<T>

Converts an Arc into a OffsetArc. This consumes the Arc, so the refcount is not modified.

source

pub fn from_raw_offset(a: OffsetArc<T>) -> Self

Converts a OffsetArc into an Arc. This consumes the OffsetArc, so the refcount is not modified.

source

pub fn try_unwrap(this: Self) -> Result<T, Self>

Returns the inner value, if the Arc has exactly one strong reference.

Otherwise, an Err is returned with the same Arc that was passed in.

§Examples

use triomphe::Arc;

let x = Arc::new(3);
assert_eq!(Arc::try_unwrap(x), Ok(3));

let x = Arc::new(4);
let _y = Arc::clone(&x);
assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);

source §

impl<T> Arc<[T]>

source

pub unsafe fn from_raw_slice(ptr: *const [T]) -> Self

Reconstruct the Arc<[T]> from a raw pointer obtained from into_raw().

Arc::from_raw should accept unsized types, but this is not trivial to do correctly until the feature pointer_bytes_offsets is stabilized. This is stopgap solution for slices.

§Safety

The given pointer must be a valid pointer to [T] that came from Arc::into_raw.
After from_raw_slice, the pointer must not be accessed.

source §

impl<T: ?Sized> Arc<T>

source

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

Convert the Arc<T> to a raw pointer, suitable for use across FFI

Note: This returns a pointer to the data T, which is offset in the allocation.

It is recommended to use OffsetArc for this.

source

pub fn as_ptr(&self) -> *const T

Returns the raw pointer.

Same as into_raw except self isn’t consumed.

source

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

Produce a pointer to the data that can be converted back to an Arc. This is basically an &Arc<T>, without the extra indirection. It has the benefits of an &T but also knows about the underlying refcount and can be converted into more Arc<T>s if necessary.

source

pub fn heap_ptr(&self) -> *const c_void

Returns the address on the heap of the Arc itself – not the T within it – for memory reporting.

source

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

Test pointer equality between the two Arcs, i.e. they must be the same allocation

source §

impl<T> Arc<MaybeUninit<T>>

source

pub fn new_uninit() -> Self

Create an Arc contains an MaybeUninit<T>.

source

pub fn write(&mut self, val: T) -> &mut T

👎Deprecated since 0.1.7: this function previously was UB and now panics for non-unique Arcs. Use UniqueArc::write instead.

Calls MaybeUninit::write on the value contained.

§Panics

If the Arc is not unique.

source

pub fn as_mut_ptr(&mut self) -> *mut MaybeUninit<T>

Obtain a mutable pointer to the stored MaybeUninit<T>.

source

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

§Safety

Must initialize all fields before calling this function.

source §

impl<T> Arc<[MaybeUninit<T>]>

source

pub fn new_uninit_slice(len: usize) -> Self

Create an Arc contains an array [MaybeUninit<T>] of len.

source

pub fn as_mut_slice(&mut self) -> &mut [MaybeUninit<T>]

👎Deprecated since 0.1.8: this function previously was UB and now panics for non-unique Arcs. Use UniqueArc or get_mut instead.

Obtain a mutable slice to the stored [MaybeUninit<T>].

source

pub unsafe fn assume_init(self) -> Arc<[T]>

§Safety

Must initialize all fields before calling this function.

source §

impl<T: Clone> Arc<T>

source

pub fn make_mut(this: &mut Self) -> &mut T

Makes a mutable reference to the Arc, cloning if necessary

This is functionally equivalent to Arc::make_mut from the standard library.

If this Arc is uniquely owned, make_mut() will provide a mutable reference to the contents. If not, make_mut() will create a new Arc with a copy of the contents, update this to point to it, and provide a mutable reference to its contents.

This is useful for implementing copy-on-write schemes where you wish to avoid copying things if your Arc is not shared.

source

pub fn make_unique(this: &mut Self) -> &mut UniqueArc<T>

Makes a UniqueArc from an Arc, cloning if necessary.

If this Arc is uniquely owned, make_unique() will provide a UniqueArc containing this. If not, make_unique() will create a new Arc with a copy of the contents, update this to point to it, and provide a UniqueArc to it.

This is useful for implementing copy-on-write schemes where you wish to avoid copying things if your Arc is not shared.

source

pub fn unwrap_or_clone(this: Arc<T>) -> T

If we have the only reference to T then unwrap it. Otherwise, clone T and return the clone.

Assuming arc_t is of type Arc<T>, this function is functionally equivalent to (*arc_t).clone(), but will avoid cloning the inner value where possible.

source §

impl<T: ?Sized> Arc<T>

source

pub fn get_mut(this: &mut Self) -> Option<&mut T>

Provides mutable access to the contents if the Arc is uniquely owned.

source

pub fn get_unique(this: &mut Self) -> Option<&mut UniqueArc<T>>

Provides unique access to the arc if the Arc is uniquely owned.

source

pub fn is_unique(&self) -> bool

Whether or not the Arc is uniquely owned (is the refcount 1?).

source

pub fn count(this: &Self) -> usize

Gets the number of Arc pointers to this allocation

source

pub fn try_unique(this: Self) -> Result<UniqueArc<T>, Self>

Returns a UniqueArc if the Arc has exactly one strong reference.

Otherwise, an Err is returned with the same Arc that was passed in.

§Examples

use triomphe::{Arc, UniqueArc};

let x = Arc::new(3);
assert_eq!(UniqueArc::into_inner(Arc::try_unique(x).unwrap()), 3);

let x = Arc::new(4);
let _y = Arc::clone(&x);
assert_eq!(
    *Arc::try_unique(x).map(UniqueArc::into_inner).unwrap_err(),
    4,
);