## UniqueArc

# Struct UniqueArc

Source

    pub struct UniqueArc<T: ?Sized, A: Allocator = Global> { /* 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, Global>

Source

#### pub fn new(value: T) -> Self

🔬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§

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

Source

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

🔬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: ?Sized, A: Allocator> UniqueArc<T, A>

Source

#### pub fn into_arc(this: Self) -> 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: ?Sized, A: Allocator + Clone> UniqueArc<T, A>

Source

#### pub fn downgrade(this: &Self) -> 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: ?Sized, A: Allocator> AsMut<T> for UniqueArc<T, A>

Source§

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

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

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

Source§

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

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

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

Source§

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

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Mutably borrows from an owned value. Read more
Source§

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

Source§

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

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

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

Source§

#### type Target = T

The resulting type after dereferencing.
Source§

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

Dereferences the value.
Source§

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

Source§

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

Mutably dereferences the value.
Source§

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

Source§

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

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

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

Source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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

Source§

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

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: ?Sized + Ord, A: Allocator> Ord for UniqueArc<T, A>

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: ?Sized + PartialEq, A: Allocator> PartialEq for UniqueArc<T, A>

Source§

#### fn eq(&self, other: &Self) -> 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: ?Sized + PartialOrd, A: Allocator> PartialOrd for UniqueArc<T, A>

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: ?Sized, A: Allocator> Pointer for UniqueArc<T, A>

Source§

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

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

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

Source§

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

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