UniqueArc in std::sync - Rust
Description: A uniquely owned `Arc`.

## UniqueArc

# Struct UniqueArc

Source

    pub struct UniqueArc<T, A = Global>where
        A: Allocator,
        T: ?Sized,{ /* private fields */ }

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)
Expand description

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§

Source§

### impl<T> UniqueArc<T>

Source

#### pub fn new(value: T) -> UniqueArc<T>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

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

Source

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

🔬This is a nightly-only experimental API. (`smart_pointer_try_map` #144419)

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

Source

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

🔬This is a nightly-only experimental API. (`smart_pointer_try_map` #144419)

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

Source§

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

Source

#### pub fn new_in(data: T, alloc: A) -> UniqueArc<T, A>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

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

Source§

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

Source

#### pub fn into_arc(this: UniqueArc<T, A>) -> Arc<T, A>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

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.

Source§

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

Source

#### pub fn downgrade(this: &UniqueArc<T, A>) -> Weak<T, A>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

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

## Trait Implementations§

Source§

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

Source§

#### fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.
Source§

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

Source§

#### fn as_ref(&self) -> &T

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

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

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

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

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

#### type Target = T

The resulting type after dereferencing.
Source§

#### fn deref(&self) -> &T

Dereferences the value.
Source§

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

Source§

#### fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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

Source§

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

Feeds this value into the given `Hasher`. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given `Hasher`. Read more
Source§

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

Source§

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

Comparison for two `UniqueArc`s.

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

1.21.0 · Source§

#### fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

#### fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

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

Restrict a value to a certain interval. Read more
Source§

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

Source§

#### fn eq(&self, other: &UniqueArc<T, A>) -> bool

Equality for two `UniqueArc`s.

Two `UniqueArc`s 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));

1.0.0 · Source§

#### fn ne(&self, other: &Rhs) -> bool

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

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

Source§

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

Partial comparison for two `UniqueArc`s.

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

Source§

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

Less-than comparison for two `UniqueArc`s.

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

Source§

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

‘Less than or equal to’ comparison for two `UniqueArc`s.

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

Source§

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

Greater-than comparison for two `UniqueArc`s.

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

Source§

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

‘Greater than or equal to’ comparison for two `UniqueArc`s.

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

Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

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

Source§

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

Source§

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

Source§

### impl<T> PinCoerceUnsized for UniqueArc<T>
where T: ?Sized,

Source§

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

Source§

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

Source§

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

## Auto Trait Implementations§

§

### impl<T, A> Freeze for UniqueArc<T, A>
where A: Freeze, T: ?Sized,

§

### impl<T, A> RefUnwindSafe for UniqueArc<T, A>
where A: RefUnwindSafe, T: RefUnwindSafe + ?Sized,

§

### impl<T, A> UnwindSafe for UniqueArc<T, A>
where A: UnwindSafe, T: RefUnwindSafe + UnwindSafe + ?Sized,

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

Source§

### impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

#### type Target = T

🔬This is a nightly-only experimental API. (`arbitrary_self_types` #44874)
The target type on which the method may be called.
Source§

### impl<T> ToString for T
where T: Display + ?Sized,

Source§

#### fn to_string(&self) -> String

Converts the given value to a `String`. Read more
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.