Crate arc_cyclic_builder

Source
Expand description

An extension to std::sync::Arc that adds Arc::new_cyclic_builder, and ArcCyclicBuilder<T> - a generalization of Arc::new_cyclic.

This comes in handy when dealing with objects that have fallible / async constructors. In these cases, the fact that Arc::new_cyclic takes an infallible, synchronous closure precludes it from being used.

§Example

Constructing a self-referential Gadget with a fallible async constructor.

use arc_cyclic_builder::ArcCyclicBuilderExt;
use std::io;
use std::sync::{Arc, Weak};

struct Gadget {
    me: Weak<Gadget>,
}

impl Gadget {
    async fn new(me: Weak<Gadget>) -> io::Result<Self> {
        Ok(Gadget { me })
    }
}

async fn create_gadget() -> io::Result<Arc<Gadget>> {
    let builder = Arc::new_cyclic_builder();
    let gadget = Gadget::new(builder.weak()).await?;
    Ok(builder.build(gadget))
}

§(Un)Safety

At the time of writing (8/22/2022), the stable public APIs of Arc and Weak are not sufficient to robustly implement ArcCyclicBuilder outside the context of the std itself. Instead, we’ve had to do something quite unsafe to get this code working…

Namely, we’ve had to make assumptions about the internal representation of Arc and Weak, and written the code assuming they will not change out from under us.

This is, by all accounts, a Really Bad Idea™️, since the std makes no guarantees as to the stability of these type’s internal representations, and could silently change them at any point.

§Road to Safety

…that said, we’re willing to bet that it’s highly unlikely that the representation of Arc/Weak is going to change in the near future, and that this code will continue to work fine (at least for a while).

Of course, leaving this kind of risk in the codebase isn’t a great idea, as while unit tests and MIRI tests serve as a reasonable early-warning indicator if the Arc/Weak representations have changed, ultimately, this code needs to land upstream in the std.

TODO: add links to any upstream PRs we end up sending out

Structs§

Traits§