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

Struct UniqueArc

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

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

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

Creates a new UniqueArc in the provided allocator.

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

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

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§

Compares and returns the maximum of two values. Read more

1.21.0§

Compares and returns the minimum of two values. Read more

1.50.0§

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§

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

Formats the value using the given formatter. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of[From](../convert/trait.From.html "trait std::convert::From")<T> for U chooses to do.

🔬This is a nightly-only experimental API. (arbitrary_self_types #44874)

The target type on which the method may be called.

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.