Struct UniqueArc

struct UniqueArc<T: ?Sized, A: Allocator = crate::alloc::Global> { ... }

A uniquely owned Arc.

This represents an Arc that is known to be uniquely owned -- that is, have exactly one strong reference. Multiple weak pointers can be created, but attempts to upgrade those to strong references will fail unless the UniqueArc they point to has been converted into a regular Arc.

Because it is uniquely owned, the contents of a UniqueArc can be freely mutated. A common use case is to have an object be mutable during its initialization phase but then have it become immutable and converted to a normal Arc.

This can be used as a flexible way to create cyclic data structures, as in the example below.

#![feature(unique_rc_arc)]
use std::sync::{Arc, Weak, UniqueArc};

struct Gadget {
    me: Weak<Gadget>,
}

fn create_gadget() -> Option<Arc<Gadget>> {
    let mut rc = UniqueArc::new(Gadget {
        me: Weak::new(),
    });
    rc.me = UniqueArc::downgrade(&rc);
    Some(UniqueArc::into_arc(rc))
}

create_gadget().unwrap();

An advantage of using UniqueArc over Arc::new_cyclic to build cyclic data structures is that Arc::new_cyclic's data_fn parameter cannot be async or return a Result. As shown in the previous example, UniqueArc allows for more flexibility in the construction of cyclic data, including fallible or async constructors.

Implementations

impl<T> UniqueArc<T, crate::alloc::Global>

fn new(value: T) -> Self

Creates a new UniqueArc.

Weak references to this UniqueArc can be created with UniqueArc::downgrade. Upgrading these weak references will fail before the UniqueArc has been converted into an Arc. After converting the UniqueArc into an Arc, any weak references created beforehand will point to the new Arc.

fn map<U, impl FnOnce(T) -> U: FnOnce(T) -> U>(this: Self, f: impl FnOnce(T) -> U) -> UniqueArc<U>

Maps the value in a UniqueArc, reusing the allocation if possible.

f is called on a reference to the value in the UniqueArc, and the result is returned, also in a UniqueArc.

Note: this is an associated function, which means that you have to call it as UniqueArc::map(u, f) instead of u.map(f). This is so that there is no conflict with a method on the inner type.

Examples

#![feature(smart_pointer_try_map)]
#![feature(unique_rc_arc)]

use std::sync::UniqueArc;

let r = UniqueArc::new(7);
let new = UniqueArc::map(r, |i| i + 7);
assert_eq!(*new, 14);

fn try_map<R, impl FnOnce(T) -> R: FnOnce(T) -> R>(this: Self, f: impl FnOnce(T) -> R) -> <<R as >::Residual as Residual<UniqueArc<<R as >::Output>>>::TryType
where
    R: Try,
    <R as >::Residual: Residual<UniqueArc<<R as >::Output>>

Attempts to map the value in a UniqueArc, reusing the allocation if possible.

f is called on a reference to the value in the UniqueArc, and if the operation succeeds, the result is returned, also in a UniqueArc.

Note: this is an associated function, which means that you have to call it as UniqueArc::try_map(u, f) instead of u.try_map(f). This is so that there is no conflict with a method on the inner type.

Examples

#![feature(smart_pointer_try_map)]
#![feature(unique_rc_arc)]

use std::sync::UniqueArc;

let b = UniqueArc::new(7);
let new = UniqueArc::try_map(b, u32::try_from).unwrap();
assert_eq!(*new, 7);

impl<T, A: Allocator> UniqueArc<T, A>

fn new_in(data: T, alloc: A) -> Self

Creates a new UniqueArc in the provided allocator.

Weak references to this UniqueArc can be created with UniqueArc::downgrade. Upgrading these weak references will fail before the UniqueArc has been converted into an Arc. After converting the UniqueArc into an Arc, any weak references created beforehand will point to the new Arc.

impl<T: ?Sized, A: Allocator + Clone> UniqueArc<T, A>

fn downgrade(this: &Self) -> Weak<T, A>

Creates a new weak reference to the UniqueArc.

Attempting to upgrade this weak reference will fail before the UniqueArc has been converted to a Arc using UniqueArc::into_arc.

impl<T: ?Sized, A: Allocator> UniqueArc<T, A>

fn into_arc(this: Self) -> Arc<T, A>

Converts the UniqueArc into a regular Arc.

This consumes the UniqueArc and returns a regular Arc that contains the value that is passed to into_arc.

Any weak references created before this method is called can now be upgraded to strong references.

impl<P, T> Receiver for UniqueArc<T, A>

impl<T> Any for UniqueArc<T, A>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for UniqueArc<T, A>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for UniqueArc<T, A>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for UniqueArc<T, A>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToString for UniqueArc<T, A>

fn to_string(self: &Self) -> String

impl<T, A> Freeze for UniqueArc<T, A>

impl<T, A> RefUnwindSafe for UniqueArc<T, A>

impl<T, A> UnwindSafe for UniqueArc<T, A>

impl<T, U> Into for UniqueArc<T, A>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for UniqueArc<T, A>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for UniqueArc<T, A>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<T: ?Sized + Eq, A: Allocator> Eq for UniqueArc<T, A>

impl<T: ?Sized + Hash, A: Allocator> Hash for UniqueArc<T, A>

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

impl<T: ?Sized + Ord, A: Allocator> Ord for UniqueArc<T, A>

fn cmp(self: &Self, other: &UniqueArc<T, A>) -> Ordering

Comparison for two UniqueArcs.

The two are compared by calling cmp() on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;
use std::cmp::Ordering;

let five = UniqueArc::new(5);

assert_eq!(Ordering::Less, five.cmp(&UniqueArc::new(6)));

impl<T: ?Sized + PartialEq, A: Allocator> PartialEq for UniqueArc<T, A>

fn eq(self: &Self, other: &Self) -> bool

Equality for two UniqueArcs.

Two UniqueArcs are equal if their inner values are equal.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;

let five = UniqueArc::new(5);

assert!(five == UniqueArc::new(5));

impl<T: ?Sized + PartialOrd, A: Allocator> PartialOrd for UniqueArc<T, A>

fn partial_cmp(self: &Self, other: &UniqueArc<T, A>) -> Option<Ordering>

Partial comparison for two UniqueArcs.

The two are compared by calling partial_cmp() on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;
use std::cmp::Ordering;

let five = UniqueArc::new(5);

assert_eq!(Some(Ordering::Less), five.partial_cmp(&UniqueArc::new(6)));

fn lt(self: &Self, other: &UniqueArc<T, A>) -> bool

Less-than comparison for two UniqueArcs.

The two are compared by calling < on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;

let five = UniqueArc::new(5);

assert!(five < UniqueArc::new(6));

fn le(self: &Self, other: &UniqueArc<T, A>) -> bool

'Less than or equal to' comparison for two UniqueArcs.

The two are compared by calling <= on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;

let five = UniqueArc::new(5);

assert!(five <= UniqueArc::new(5));

fn gt(self: &Self, other: &UniqueArc<T, A>) -> bool

Greater-than comparison for two UniqueArcs.

The two are compared by calling > on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;

let five = UniqueArc::new(5);

assert!(five > UniqueArc::new(4));

fn ge(self: &Self, other: &UniqueArc<T, A>) -> bool

'Greater than or equal to' comparison for two UniqueArcs.

The two are compared by calling >= on their inner values.

Examples

#![feature(unique_rc_arc)]
use std::sync::UniqueArc;

let five = UniqueArc::new(5);

assert!(five >= UniqueArc::new(5));

impl<T: ?Sized + Sync + Send, A: Allocator + Send> Send for UniqueArc<T, A>

impl<T: ?Sized + Sync + Send, A: Allocator + Sync> Sync for UniqueArc<T, A>

impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn for UniqueArc<T>

impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized for UniqueArc<T, A>

impl<T: ?Sized + fmt::Debug, A: Allocator> Debug for UniqueArc<T, A>

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

impl<T: ?Sized + fmt::Display, A: Allocator> Display for UniqueArc<T, A>

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

impl<T: ?Sized> PinCoerceUnsized for UniqueArc<T>

impl<T: ?Sized, A: Allocator> AsMut for UniqueArc<T, A>

fn as_mut(self: &mut Self) -> &mut T

impl<T: ?Sized, A: Allocator> AsRef for UniqueArc<T, A>

fn as_ref(self: &Self) -> &T

impl<T: ?Sized, A: Allocator> Borrow for UniqueArc<T, A>

fn borrow(self: &Self) -> &T

impl<T: ?Sized, A: Allocator> BorrowMut for UniqueArc<T, A>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T: ?Sized, A: Allocator> Deref for UniqueArc<T, A>

fn deref(self: &Self) -> &T

impl<T: ?Sized, A: Allocator> DerefMut for UniqueArc<T, A>

fn deref_mut(self: &mut Self) -> &mut T

impl<T: ?Sized, A: Allocator> DerefPure for UniqueArc<T, A>

impl<T: ?Sized, A: Allocator> Drop for UniqueArc<T, A>

fn drop(self: &mut Self)

impl<T: ?Sized, A: Allocator> Pointer for UniqueArc<T, A>

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

impl<T: ?Sized, A: Allocator> Unpin for UniqueArc<T, A>