v1.0 release

[notgull]

I want to add a oneshot channel to smol's public API, mainly for discoverability. Rather than re-inventing the wheel and coding one, I figure why not just re-export this crate?

However smol is a stable crate, so this crate would need to have a stable (v1.0) release if that were to happen.

Are there any issues that would prevent a stable release? I'm willing to help if you'll have me.

cc @madsmtm, @smol-rs/admins

[madsmtm]

Looking at the public API, a few thoughts come to mind:

• Maybe make the error types opaque? Though there is a nicety in that they currently match those in std::sync::mpsc.
• Would be nice to have #![cfg_attr(docsrs, feature(doc_auto_cfg))] to make it easier to see which things are cfg-gated behind the std feature.
• Maybe remove the "async" feature altogether, it seems weird to have it optional when Future is available in core? If not possible because of the ReceiverWaker stuff, then maybe it makes sense to expose different functions for each of the different use-cases (would also avoid the panic if calling both poll and recv).
• [Ref]UnwindSafe impls would be nice.

[notgull]

Pinging @zeenix since this has been discussed re: adding async-broadcast to smol

[faern]

Thanks for opening this issue. oneshot has been around for a while now. Yeah, maybe it's time to stabilize it soon?

* Maybe make the error types opaque? Though there is a nicety in that they currently match those in `std::sync::mpsc`.

Which error specifically? I think the errors currently has a pretty clean and nice API surface.

* Would be nice to have `#![cfg_attr(docsrs, feature(doc_auto_cfg))]` to make it easier to see which things are `cfg`-gated behind the `std` feature.

Indeed! Making the features more discoverable would be great. I would be all for merging something like this.

* Maybe remove the `"async"` feature altogether, it seems weird to have it optional when `Future` is available in `core`? If not possible because of the `ReceiverWaker` stuff, then maybe it makes sense to expose different functions for each of the different use-cases (would also avoid the panic if calling both `poll` and `recv`).

async being feature gated is not about dependencies, but rather compiling the code as optimally as possible. Some types and methods can get rid of some code if one or the other feature is not enabled. My main motivation for writing oneshot was to have a channel impl that could easily pass messages between async and blocking operations of a program. But it's still valid to use it within only one type, and then having it compile to whatever is optimal for only that is neat. But I have to admit that I have not benched this to validate if this is a valid reason or not. I agree that both the code and the usage can be a bit simpler if we just have it on at all times.

* `[Ref]UnwindSafe` impls would be nice.

I have to look into this. I have no opinion at this point. Do you have a use case in mind that you can describe?

[zeenix]

Pinging @zeenix since this has been discussed re: adding async-broadcast to smol

I'm not sure about the relevance here. We can add oneshot to smol, independently of async-broadcast addition.

[faern]

Maybe make the error types opaque? Though there is a nicety in that they currently match those in std::sync::mpsc.

Is this what you meant @madsmtm: #56 ?

[faern]

I opened a milestone for this! So it can be tracked: https://github.com/faern/oneshot/milestone/1

There are some unresolved questions about the API that require some thinking about and maybe discussion. I'm thinking we can collect a bunch of API breaking changes into a 0.2.0 release and see how it works out in practice before going all the way to 1.0.0

[madsmtm]

Sorry, messed up my notifications and forgot to answer before.

Maybe make the error types opaque? Though there is a nicety in that they currently match those in std::sync::mpsc.

Is this what you meant @madsmtm: #56 ?

Yup, that's what I meant ;). It can always be reverted in a later version once you're really certain that that's what the error should look like.

Indeed! Making the features more discoverable would be great. I would be all for merging something like this.

I'll whip up a PR.

* Maybe remove the `"async"` feature altogether, it seems weird to have it optional when `Future` is available in `core`? If not possible because of the `ReceiverWaker` stuff, then maybe it makes sense to expose different functions for each of the different use-cases (would also avoid the panic if calling both `poll` and `recv`).

async being feature gated is not about dependencies, but rather compiling the code as optimally as possible. Some types and methods can get rid of some code if one or the other feature is not enabled. My main motivation for writing oneshot was to have a channel impl that could easily pass messages between async and blocking operations of a program. But it's still valid to use it within only one type, and then having it compile to whatever is optimal for only that is neat. But I have to admit that I have not benched this to validate if this is a valid reason or not. I agree that both the code and the usage can be a bit simpler if we just have it on at all times.

That's fair. I see you've also given it some more thought in #57. I'm fine with both, just wanted to make sure it was considered.

* `[Ref]UnwindSafe` impls would be nice.

I have to look into this. I have no opinion at this point. Do you have a use case in mind that you can describe?

Nope. I guess could conjure something up, but it'd be entirely contrived. Just noted it for completeness.

I'm thinking we can collect a bunch of API breaking changes into a 0.2.0 release and see how it works out in practice before going all the way to 1.0.0

Good idea! And then, if you find that there's no / limited breaking changes between v0.2 and v1.0, it may even be possible to do the semver trick.

[faern]

@madsmtm

I'll whip up a PR.

Already done, as part of #57

[faern]

Anyone who have suggestions or questions regarding a 1.0 release. Please create separate issues, and I'll add it to the milestone. This issue is slightly getting out of hand by there being multiple parallel topics.

[faern]

I just published oneshot 0.2.0: https://crates.io/crates/oneshot/0.2.0

This address some of the stuff brought up in this 1.0-thread.

I want to run with this API for a bit and see if there is any feedback coming in.

We'll see for how long we keep this API. Because I'm also considering adopting the same API as the standard library's experimental oneshot channels: https://doc.rust-lang.org/nightly/std/sync/oneshot/index.html. That implementation has way fewer features compared to this crate. But the main difference I'm looking at is to not have any receiving methods that take self as a reference. Only consuming receive. On errors the error contains the Receiver again. This might be more complicated to use, or maybe not? I would love some feedback here.

The standard library oneshot library does not support async receiving, which makes it a bit pointless IMHO. And to implement that they would need to implement receiving over non-consuming references, since that is what Future::poll takes. But I guess that is not in scope for the standard library right now.

If you a user of oneshot and you have interest in having it in the standard library, feel free to visit rust-lang/rust#143674 (comment) and read + comment I guess :).