Breaking changes before releasing crossbeam-channel 1.0

[ghost]

In early 2019, I'd like to publish version 1.0 of crossbeam-channel.

This issue tracks potential breaking changes for the final release.

Please vote on suggestions with 👍 and 👎, or write a comment.

[ghost]

Change the signature of Select::recv() and Select::send() so that we use a custom type Token (similar to Token in mio) instead of indices of type usize. The Token type would wrap the index so that we get some type safety.

The interface of Select::recv() would take one of these forms:

1. fn recv<T>(&mut self, r: &Receiver<T>) -> Token
2. fn recv<T>(&mut self, r: &Receiver<T>, token: Token)

See also: #245 (comment)

[ghost]

Use the word "closed" instead of "disconnected". That means we'd rename variants like TryRecvError::Disconnected to TryRecvError::Closed.

Prior art:

• std::sync::mpsc uses "disconnected".
• chan uses "closed".
• tokio-channel uses "closed".
• futures::sync::mpsc uses "closed".
• Golang uses "closed".

See also: rust-lang/futures-rs#1346

[ghost]

Not a breaking change, but a new feature.

Add methods Sender::disconnect() and Receiver::disconnect() to explicitly close channels.

See also: #236

[ghost]

Not a breaking change, but a new feature.

Add methods Sender::is_disconnected() and Receiver::is_disconnected() that check whether the channel has been disconnected.

[Thomasdezeeuw]

@stjepang I'm sure not if you want to keep this as a meta issue or also discuss in it, but here are some of my toughs.

Regarding the use of a token/index in Select::recv(), can we do better then the generic name Token? For mio I proposed EventId/event::Id (tokio-rs/mio#905).

I'm also against adding {Sender, Receiver}::disconnect() methods. Because in Rust we don't have to think about cleanup as Drop will take of that for us (for the most part). I realise this will not change, but it might confuse people new to the API.

[ghost]

@Thomasdezeeuw Thank you for weighing in! Yes, I'm still keeping this meta-issue so that we don't forget about anything that needs another careful look before stabilization.

I'd be happy with EventId, that sounds good. In fact, it'd be great to choose the same name in crossbeam-channel and mio for consistency.

I'm increasingly feeling .disconnect() should not be added, too. There seem to be more voices against than for it at this point.

[ghost]

Not a breaking change, but a small API addition:

impl<T> Sender<T> {
    fn connected_to(&self, r: &Receiver<T>) -> bool;
}

impl<T> Receiver<T> {
    fn connected_to(&self, s: &Sender<T>) -> bool;
}

These methods check whether a sender and a receiver belong to the same channel.

[ghost]

An idea by @mgeier: Make SendError and RecvError single-variant enums:

enum RecvError {
    Closed,
}

enum SendError<T> {
    Closed(T),
}

[ghost]

Another idea by @mgeier: Rename Timeout error variants to Empty/Full:

enum RecvTimeoutError {
    Empty,
    Closed,
}

enum SendTimeoutError<T> {
    Full(T),
    Closed(T),
}

[ghost]

I just realized why "disconnect" might be preferable to "close".

When we "close" a Unix pipe or a channel in other programming languages, the handle is not dropped. That means one can do:

chan.close();
chan.send(foo); // this will panic, abort, or throw an exception

In Rust this is not possible. In fact, once all senders or all receivers get dropped, the channel is really "disconnected" because we literally don't have a sender handle connected to a receiver handle anymore.

Moreover, closing tends to be a manual action you have to explicitly request, whereas disconnection tends to be an automatic action.

Does this make sense to anyone?