Struct Arc 

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

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

impl<T> Arc<T>

pub fn new(data: T) -> Arc<T>

Construct an Arc<T>

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.

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

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

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

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

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

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);

pub fn into_unique(this: Arc<T>) -> Option<UniqueArc<T>>

Converts the Arc to UniqueArc if the Arc has exactly one strong reference.

Otherwise, None is returned and the Arc is dropped.

If Arc::into_unique is called on every clone of this Arc, it is guaranteed that exactly one of the calls returns a UniqueArc. This means in particular that the inner data is not dropped. This can be useful when it is desirable to recover the inner value in a way that does not require coordination amongst the various copies of Arc.

Arc::try_unique is conceptually similar to Arc::into_unique, but it is meant for different use-cases. If used as a direct replacement for Arc::into_unique, such as with the expression Arc::try_unique(this).ok(), then it does not give the same guarantee as described in the previous paragraph.

For more information, see the examples below and read the documentation of Arc::try_unique.

Examples

use triomphe::Arc;

let x = Arc::new(3);
let y = Arc::clone(&x);

// Two threads calling `Arc::into_inner` on both clones of an `Arc`:
let x_thread = std::thread::spawn(|| Arc::into_unique(x));
let y_thread = std::thread::spawn(|| Arc::into_unique(y));

let x_unique = x_thread.join().unwrap();
let y_unique = y_thread.join().unwrap();

// One of the threads is guaranteed to receive the inner value:
assert!((x_unique.is_some() && y_unique.is_none()) || (x_unique.is_none() && y_unique.is_some()));
// The result could also be `(None, None)` if the threads called
// `Arc::try_unique(x).ok()` and `Arc::try_unique(y).ok()` instead.

impl<T> Arc<[T]>

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

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.

impl<T> Arc<T>

where T: ?Sized,

pub fn into_raw(this: Arc<T>) -> *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.

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

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.

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

Returns the raw pointer.

Same as into_raw except self isn’t consumed.

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.

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.

pub fn strong_count(this: &Arc<T>) -> usize

The reference count of this Arc.

The number does not include borrowed pointers, or temporary Arc pointers created with functions like ArcBorrow::with_arc.

The function is called strong_count to mirror std::sync::Arc::strong_count, however triomphe::Arc does not support weak references.

pub fn ptr_eq(this: &Arc<T>, other: &Arc<T>) -> bool

Returns true if the two Arcs point to the same allocation in a vein similar to ptr::eq. This function ignores the metadata of dyn Trait pointers.

impl<T> Arc<MaybeUninit<T>>

pub fn new_uninit() -> Arc<MaybeUninit<T>>

Create an Arc contains an MaybeUninit<T>.

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.

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

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

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

Safety

Must initialize all fields before calling this function.

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

pub fn new_uninit_slice(len: usize) -> Arc<[MaybeUninit<T>]>

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

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>].

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

Safety

Must initialize all fields before calling this function.

impl<T> Arc<T>

where T: Clone,

pub fn make_mut(this: &mut Arc<T>) -> &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.

pub fn make_unique(this: &mut Arc<T>) -> &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.

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.

impl<T> Arc<T>

where T: ?Sized,

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

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

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

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

pub fn is_unique(&self) -> bool

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

pub fn count(this: &Arc<T>) -> usize

Gets the number of Arc pointers to this allocation

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

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,
);

impl<H, T> Arc<HeaderSlice<H, [T]>>

pub fn from_header_and_iter<I>(header: H, items: I) -> Arc<HeaderSlice<H, [T]>>

where I: Iterator<Item = T> + ExactSizeIterator,

Creates an Arc for a HeaderSlice using the given header struct and iterator to generate the slice. The resulting Arc will be fat.

pub fn from_header_and_slice(header: H, items: &[T]) -> Arc<HeaderSlice<H, [T]>>

where T: Copy,

Creates an Arc for a HeaderSlice using the given header struct and iterator to generate the slice. The resulting Arc will be fat.

pub fn from_header_and_vec(header: H, v: Vec<T>) -> Arc<HeaderSlice<H, [T]>>

Creates an Arc for a HeaderSlice using the given header struct and vec to generate the slice. The resulting Arc will be fat.

impl<H> Arc<HeaderSlice<H, str>>

pub fn from_header_and_str(header: H, string: &str) -> Arc<HeaderSlice<H, str>>

Creates an Arc for a HeaderSlice using the given header struct and a str slice to generate the slice. The resulting Arc will be fat.

impl<H, T> Arc<HeaderSlice<HeaderWithLength<H>, [T]>>

pub fn into_thin(a: Arc<HeaderSlice<HeaderWithLength<H>, [T]>>) -> ThinArc<H, T>

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

pub fn from_thin(a: ThinArc<H, T>) -> Arc<HeaderSlice<HeaderWithLength<H>, [T]>>

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

impl<H, T> Arc<HeaderSliceWithLengthProtected<H, T>>

pub fn protected_into_thin( a: Arc<HeaderSliceWithLengthProtected<H, T>>, ) -> ThinArc<H, T>

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

pub fn protected_from_thin( a: ThinArc<H, T>, ) -> Arc<HeaderSliceWithLengthProtected<H, T>>

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

Trait Implementations

impl<T> AsRef<T> for Arc<T>

where T: ?Sized,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Borrow<T> for Arc<T>

where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T> Clone for Arc<T>

where T: ?Sized,

fn clone(&self) -> Arc<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Arc<T>

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<T> Default for Arc<T>

where T: Default,

fn default() -> Arc<T>

Returns the “default value” for a type.

impl<T> Deref for Arc<T>

where T: ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> Display for Arc<T>

where T: Display + ?Sized,

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

Formats the value using the given formatter.

impl<T> Drop for Arc<T>

where T: ?Sized,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<&[T]> for Arc<[T]>

where T: Copy,

fn from(slice: &[T]) -> Arc<[T]>

Converts to this type from the input type.

impl From<&str> for Arc<str>

fn from(s: &str) -> Arc<str>

Converts to this type from the input type.

impl<T> From<Arc<HeaderSlice<(), T>>> for Arc<T>

where T: ?Sized,

fn from(this: Arc<HeaderSlice<(), T>>) -> Arc<T>

Converts to this type from the input type.

impl<T> From<Arc<T>> for Arc<HeaderSlice<(), T>>

where T: ?Sized,

fn from(this: Arc<T>) -> Arc<HeaderSlice<(), T>>

Converts to this type from the input type.

impl<T> From<Box<T>> for Arc<T>

fn from(b: Box<T>) -> Arc<T>

Converts to this type from the input type.

impl From<String> for Arc<str>

fn from(s: String) -> Arc<str>

Converts to this type from the input type.

impl<T> From<T> for Arc<T>

fn from(t: T) -> Arc<T>

Converts to this type from the input type.

impl<T> From<Vec<T>> for Arc<[T]>

fn from(v: Vec<T>) -> Arc<[T]>

Converts to this type from the input type.

impl<A> FromIterator<A> for Arc<[A]>

fn from_iter<T>(iter: T) -> Arc<[A]>

where T: IntoIterator<Item = A>,

Creates a value from an iterator.

impl<T> Hash for Arc<T>

where T: Hash + ?Sized,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Arc<T>

where T: Ord + ?Sized,

fn cmp(&self, other: &Arc<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq for Arc<T>

where T: PartialEq + ?Sized,

fn eq(&self, other: &Arc<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Arc<T>) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Arc<T>

where T: PartialOrd + ?Sized,

fn partial_cmp(&self, other: &Arc<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Arc<T>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Arc<T>) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Arc<T>) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Arc<T>) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Pointer for Arc<T>

where T: ?Sized,

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

Formats the value using the given formatter.

impl<T> Eq for Arc<T>

where T: Eq + ?Sized,

impl<T> Send for Arc<T>

where T: Sync + Send + ?Sized,

impl<T> Sync for Arc<T>

where T: Sync + Send + ?Sized,

impl<T> UnwindSafe for Arc<T>

where T: RefUnwindSafe + ?Sized,