2.x: make Obs.combineLatest consistent with Flowable + doc cornercase (…

…#4987) * 2.x: make Obs.combineLatest consistent with Flowable + doc cornercase * early termination to cancel the other sources
ReactiveX · Jan 12, 2017 · d1cd153 · d1cd153
1 parent 3768a53
commit d1cd153
Show file tree

Hide file tree

Showing 6 changed files with 449 additions and 4 deletions.
diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java
@@ -143,6 +143,10 @@ public static int bufferSize() {
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -180,6 +184,10 @@ public static <T, R> Flowable<R> combineLatest(Publisher<? extends T>[] sources,
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -217,6 +225,10 @@ public static <T, R> Flowable<R> combineLatest(Function<? super Object[], ? exte
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -262,6 +274,10 @@ public static <T, R> Flowable<R> combineLatest(Publisher<? extends T>[] sources,
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -300,6 +316,10 @@ public static <T, R> Flowable<R> combineLatest(Iterable<? extends Publisher<? ex
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -343,6 +363,10 @@ public static <T, R> Flowable<R> combineLatest(Iterable<? extends Publisher<? ex
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -382,6 +406,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Publisher<? extends T>[
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -421,6 +449,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Function<? super Object
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -462,6 +494,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Function<? super Object
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -509,6 +545,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Publisher<? extends T>[
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -548,6 +588,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Iterable<? extends Publ
      * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
      * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
      * {@code Function<Integer[], R>} passed to the method would trigger a {@code ClassCastException}.
+     * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
      *
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -588,6 +632,10 @@ public static <T, R> Flowable<R> combineLatestDelayError(Iterable<? extends Publ
      * source Publishers each time an item is received from either of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -629,6 +677,10 @@ public static <T1, T2, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -674,6 +726,10 @@ public static <T1, T2, T3, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -723,6 +779,10 @@ public static <T1, T2, T3, T4, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -777,6 +837,10 @@ public static <T1, T2, T3, T4, T5, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -835,6 +899,10 @@ public static <T1, T2, T3, T4, T5, T6, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -898,6 +966,10 @@ public static <T1, T2, T3, T4, T5, T6, T7, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -965,6 +1037,10 @@ public static <T1, T2, T3, T4, T5, T6, T7, T8, R> Flowable<R> combineLatest(
      * source Publishers each time an item is received from any of the source Publishers, where this
      * aggregation is defined by a specified function.
      * <p>
+     * If any of the sources never produces an item but only terminates (normally or with an error), the
+     * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
+     * If that input source is also synchronous, other sources after it will not be subscribed to.
+     * <p>
      * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>