Inconsistent ordering in select APIs

[betamos]

Selecting over >=2 futures has subtle fairness issues when more than one future is ready. The current offering has a few inconsistencies in docs and naming:

1. futures::select!: pseudo-random, documented
2. futures::select_biased!: in-order, documented
3. futures::future::{select, try_select, select_ok}: in-order, undocumented
4. futures::future::select_all: in-order, documented that one should not rely on order
5. futures::stream::select: round-robin, documented
6. futures::stream::select_all: (based on FuturesUnordered - not sure), undocumented

Golang uses random order for select to prevent starvation, which is a hard-to-detect and problematic pitfall. IMO, any select API with a starvation risk should be explicitly documented as such. Even "don't rely on order" is too benign of a statement.

For user-facing behavior, I'd divide the behavior of the current offering into three classes:

• Order specified in the API. (2)
• Order not specified, but has mitigations against starvation. (1, 5, 6?)
• Order not specified, but can cause starvation. (3, 4)
  • Ideally I'd suggest eliminating this class entirely in favor of either of the other two

Initially, adding coverage of these behaviors to the existing API docstrings would be nice. Happy to create a PR upon endorsement from a maintainer.

Regarding naming, I like the precedent set by the macros: select! is starvation-protected by default, and select_biased! has explicit ordering. Following the principle of least surprise, ideally that convention could be applied to the other APIs as well. Now, going down this road would introduce breaking changes. Maybe a maintainer can chime in?

[Nemo157]

From my reading of SelectAll and FuturesUnordered I believe it will guarantee a form of round-robin. Namely that the streams will be polled round-robin if they are always ready, but a stream that is not ready will be skipped, and added to the end of the round-robin queue when it next wakes. This playground agrees with my base case that always ready streams will be polled round-robin, and this playground seems to agree that there's no starvation.

I think it would be good to add a guarantee around this to the documentation and tests that ensure it will not result in starvation when a stream is always ready.

[Xaeroxe]

This is a pretty major footgun and had me and my coworker confused for several days about why we were getting inconsistent behavior in our code. I think it's important to get this situation sorted out.