UniqueArc in std::sync - Rust (original) (raw)

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 thatArc::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.

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

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

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

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

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

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

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

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

1.21.0 · Source §

Compares and returns the maximum of two values. Read more

1.21.0 · Source §

Compares and returns the minimum of two values. Read more

1.50.0 · Source §

Restrict a value to a certain interval. Read more

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

1.0.0 · Source §

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

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

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

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

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

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