Declare subscription order for amb and ambWith in documentation.

[JakeWharton]

amb() should declare that it subscribes to the supplied observables in the order of the iterable/array. ambWith() should declare that it subscribes to the host observable before the supplied 'other' observable.

This allows consumers to explicitly rely on this ordering and a deviation from it to be a bug.

[JakeWharton]

I can send a PR for this, I just wanted to make sure that the subscription order is something that we want to put into the public API. In theory a perfectly acceptable implementation of ambWith could be amb(other, this) (but that'd be bad!).

[akarnokd]

This ordered subscribe is implied, what makes you want this to be explicitly defined?

[JakeWharton]

We have code whose behavior depends on it. It basically does behaviorSubject.ambWith(just(sentinel)) to ensure a value is always synchronously emitted downstream upon subscribe. Would the subscription order of this (or amb) change we'd never see the subject value when it was set.

…

On Thu, Feb 2, 2017, 2:09 AM David Karnok ***@***.***> wrote: This ordered subscribe is implied, what makes you want this to be explicitly defined? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#5044 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEUw5FvFu5gBiUnAD-ccvupBhhRa3ks5rYYEPgaJpZM4L0m_L> .

[akarnokd]

This looks like you need BehaviorSubject.createDefault(sentinel) (or create(sentinel) to make sure you have something to start with when subscribing.

Generally, I don't think such ordering guarantee should explicitly be declared on amb.

[JakeWharton]

That was a contrived example so your suggestion won't work in practice. I see no reason to omit ordering guarantees around subscription since the behavior in the synchronous case relies on it. Also it would be completely illogical to have any ordering but the obvious one that already exists, so this really isn't a commitment of any challenge.

…

On Thu, Feb 2, 2017, 10:07 AM David Karnok ***@***.***> wrote: This looks like you need BehaviorSubject.createDefault(sentinel) (or create(sentinel) to make sure you have something to start with when subscribing. Generally, I don't think such ordering guarantee should explicitly be declared on amb. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#5044 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEVpKoznqc6RXSatXInM85GgnfPHkks5rYfFEgaJpZM4L0m_L> .

[akarnokd]

Okay then, but don't forget to add unit tests that verify the order is actually held by the implementation (in case of another complete rewrite for 3.x). 5 base types x 3 amb types == 15 tests.

[valeriyo]

Essentially, docs should (more) explicitly state that:

assertThat(amb(just(1), just(2)).toBlocking().single()).isEqualTo(1);

[akarnokd]

Closing via #5047.