Tracking Issue for `Exclusive`

[guswynn]

Feature gate: #![feature(exclusive_wrapper)]

This is a tracking issue for the Exclusive wrapper struct.

This structure can be used to upgrade non-Sync objects into Sync ones, by only offering mutable access to the underlying object. This can be useful with Send-but-not-Sync futures (like BoxFutures)

Public API

// core::sync
#[derive(Default)]
struct Exclusive<T: ?Sized> { ... }

impl<T: ?Sized> Sync for Exclusive {}

impl<T> Exclusive<T> {
    pub const fn new(t: T) -> Self;
    pub const fn into_inner(self) -> T;
}

impl<T: ?Sized> Exclusive<T> {
    pub const fn get_mut(&mut self) -> &mut T;
    pub const fn get_pin_mut(Pin<&mut self>) -> Pin<&mut T>;
    pub const fn from_mut(&mut T) -> &mut Exclusive<T>;
    pub const fn from_pin_mut(Pin<&mut T>) -> Pin<&mut Exclusive<T>>;
}

impl<T: Future> Future for Exclusive { ... }

impl<T> From<T> for Exclusive<T> { ... }
impl<T: ?Sized> Debug for Exclusive { ... }

Steps / History

• Implementation: [core] add Exclusive to sync #97629
• Determine other nice-to-have trait impls
  • Add Exclusive forwarding impls (FnOnce, FnMut, Generator) #116241
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• None yet.

[clarfonthey]

This is probably a bikeshed, but perhaps the get_pin_mut method could be directly implemented on Pin<Exclusive<T>>, so that it can share the same name as the regular Exclusive<T> version? Then maybe both could be named get_mut, or even get since you'll have to use it to access non-mutable methods, just with exclusive access.

This does make it asymmetric with from_pin_mut, though, unless there were a Pin::exclusive method.

[guswynn]

@clarfonthey that would conflict with https://doc.rust-lang.org/std/pin/struct.Pin.html#method.get_mut

[Nemo157]

To provide some motivation I have been using a more limited internal version of this for about 3 years in async-compression. This is the sole bit of unsafety in that crate so I would love to be able to offload that onto std.

[guswynn]

@Nemo157 I think we should try to get this in at 1.66, next week ill take a look at writing a stabilization report

Hi! I've submitted PR #104057, with a few small changes:

• Added rustc_const_unstable attributes on the const fns.
  • into_inner is gated under const_exclusive_into_inner, and is blocked on const drop.
  • {get,from}_{mut,pin_mut} is gated under const_exclusive_get_mut, and is blocked on const_mut_refs.
• The From impl is now unstably const under const_convert, for consistency with the rest of the standard library.
• Exclusive<G> now implements Generator, gated under generator_trait.
• Exclusive<F> now implements FnOnce & FnMut.

I would be happy to write a stabilization PR when this passes an FCP.

[zachs18]

For the same reason that Exclusive can unconditionally implement Sync, I believe it can also unconditionally implement core::panic::RefUnwindSafe (which claims that a shared reference to the type is unwind-safe (i.e. can cross a panic boundary without introducing logic errors), which &Exclusive is, because it has no API).

I don't know if it would be that useful (even ignoring that there's been some disucssion about deprecating (Ref)UnwindSafe), but I believe it could be added after stabilization if it is wanted, so it's not urgent or blocking.

[harudagondi]

Interestingly, in bevyengine/bevy#7718, they are adding a method called read that allows shared access to their Exclusive analogue as long as the inner type implements Sync.

[alice-i-cecile]

Q: What's the use case for a SyncCell when the type is already Sync?
A: Generics, mostly. When designing an API you might not know if a type parameter is Sync or not, so you'd put it in a SyncCell. Then when you use that API with a concrete type, you can bypass the exclusivity if that type is Sync

The method above is quite useful for us, but is a contradiction with the Exclusive name of this type. As a result, we'd like to suggest renaming the type to something compatible, and adding the method linked in the PR above.

This is quite a useful type, and it would be a shame to see something limited get locked in via stabilization.

(summarized from conversation in the Bevy Discord).