oneshot Channel

[connortsui20]

Tracking Issue: #143674

This PR adds an experimental oneshot module.

Before talking about the API itself, I would prefer to get some of these questions below out of the way first. And as discussed in the ACP it would be

Unresolved Questions

• Why exactly is it okay for Sender to be Sync? Or basically, how do we boil down the discussion in Implement Sync for mpsc::Sender #111087 into a comment for the unsafe impl<T: Send> Sync for Sender<T> {}?
• Why is mpsc::Receiver !Sync but mpmc::Receiver is Sync? Should oneshot::Receiver be Sync or not?
• Should this PR try to add an is_ready method as proposed in the tracking issue? If so, then the surface of this PR would likely need to increase to add a pub(crate) fn is_disconnected method to mpmc (might even be a good idea to add that to all 3 channel flavors).
• In a similar vein to the previous question, should the first internal implementation simply be a wrapper around mpmc, or should it be a wrapper around the internal crossbeam implementation?
• Should the Sender and Receiver operations be methods or associated methods? So sender.send(msg) or Sender::send(sender, msg)? The method syntax is more consistent with the rest of the ecosystem (namely tokio)

[rustbot]

r? @tgross35

rustbot has assigned @tgross35.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[tgross35]

Maybe want to ask the unresolved questions at the ACP thread? To make sure it's seen by those already involved.

(I'll take a closer look later)

[RustyYato]

Why exactly is it okay for Sender to be Sync? Or basically, how do we boil down the discussion in #111087 into a comment for the unsafe impl<T: Send> Sync for Sender {}?

Why is mpsc::Receiver !Sync but mpmc::Receiver is Sync? Should oneshot::Receiver be Sync or not?

Because mpsc is multiple producer single consumer, and does the receiver operation via &self, so it would be incorrect to allow recv to be shared across threads because that would allow two threads to recv at the same time, which isn't allowed for a mpsc.

But mpmc is multiple producer multiple consumer, so it doesn't matter how many threads recv at the same time.

For this one, they can both be unconditionally Sync, since there is no API to go from &Sender<T> or &Reciever<T> to &T. (even via traits like Debug or Clone). In fact it looks like &Sender<T> and &Receiver<T> are entirely useless (only a Debug impl, which doesn't provide any information), which is just like Exclusive.. This is more evidence that both Sender<T> and Receiver<T> can be unconditionally Sync

[connortsui20]

Thank you for the answer!

Please let me know if I'm interpreting this right: If all methods where synchronization must occur consume self, we can say that both Sender and Receiver are Sync. For example, if threads share a &oneshot::Receiver, then none of them can call recv anyways. And this would still be compatible with the proposed is_ready method discussed in the tracking issue.

[tgross35]

I haven't gotten a chance to look into this unfortunately

r? libs

[connortsui20]

r? libs (based on this comment)

[bors]

☔ The latest upstream changes (presumably #147928) made this pull request unmergeable. Please resolve the merge conflicts.

[tgross35]

It's been a little while so
r? @joboet

Feel free to reroll if you want but you've reviewed a lot of sync module things.

[joboet]

Using the full mpmc implementation is a bit overkill here in my opinion. I think we could do better by using a OnceLock wrapped by an Rc here and adding a wait_timeout_force method to Once next to the existing wait_force.

[connortsui20]

@joboet I think I'm in agreement, though the main reason I did it like so was because of this comment from the original ACP: rust-lang/libs-team#610 (comment)

I believe that the goal was to reuse as much code as possible? I do think a OnceLock impl would probably be better in the long-term but this at least is a lot easier to reason about w.r.t the API

[tgross35]

Cc @the8472 from the above-linked comment

[the8472]

As I wrote in the comment we didn't discuss implementation too much, we just assumed crossbeam's code would be suitable. If that's inefficient for a oneshot channel and all the desired API surface can be implemented in a better way then we can replace the internals. But landing things incrementally is fine, so that can happen in a separate PR.

[connortsui20]

Sorry for the delay, I completely forgot about this!

[joboet]

Please use the builder methods for this – that also makes the alternative formatting work.

Suggested change

	f.pad("Sender { .. }")
	f.debug_struct("Sender").finish_non_exhaustive()

[connortsui20]

Ah I see, sorry I was just copying the mpmc impl (that should probably be updated too)

[joboet]

We generally don't hide imports and feature declarations in doc-examples – it's useful for users to know what a specific type is.

[joboet]

What's your motivation for making this a doc-comment?

[connortsui20]

whoops

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.