3.x: observeOn and Schedulers.from eagerness javadoc updates (#6723)

Author: akarnokd

Diff for: src/main/java/io/reactivex/rxjava3/core/Flowable.java

@@ -11386,6 +11386,11 @@ public final Flowable<T> mergeWith(@NonNull CompletableSource other) {
      * asynchronous. If strict event ordering is required, consider using the {@link #observeOn(Scheduler, boolean)} overload.
      * <p>
      * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.png" alt="">
+     * <p>
+     * This operator keeps emitting as many signals as it can on the given Scheduler's Worker thread,
+     * which may result in a longer than expected occupation of this thread. In other terms,
+     * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
+     * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>This operator honors backpressure from downstream and expects it from the source {@code Publisher}. Violating this
@@ -11406,6 +11411,7 @@ public final Flowable<T> mergeWith(@NonNull CompletableSource other) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler, boolean)
      * @see #observeOn(Scheduler, boolean, int)
+     * @see #delay(long, TimeUnit, Scheduler)
      */
     @CheckReturnValue
     @BackpressureSupport(BackpressureKind.FULL)
@@ -11424,7 +11430,6 @@ public final Flowable<T> observeOn(Scheduler scheduler) {
      * which may result in a longer than expected occupation of this thread. In other terms,
      * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
      * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
-     * <p>
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>This operator honors backpressure from downstream and expects it from the source {@code Publisher}. Violating this
@@ -11449,7 +11454,7 @@ public final Flowable<T> observeOn(Scheduler scheduler) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler)
      * @see #observeOn(Scheduler, boolean, int)
-     * @see #delay(long, TimeUnit, Scheduler)
+     * @see #delay(long, TimeUnit, Scheduler, boolean)
      */
     @CheckReturnValue
     @BackpressureSupport(BackpressureKind.FULL)
@@ -11468,7 +11473,6 @@ public final Flowable<T> observeOn(Scheduler scheduler, boolean delayError) {
      * which may result in a longer than expected occupation of this thread. In other terms,
      * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
      * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
-     * <p>
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>This operator honors backpressure from downstream and expects it from the source {@code Publisher}. Violating this
@@ -11494,7 +11498,7 @@ public final Flowable<T> observeOn(Scheduler scheduler, boolean delayError) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler)
      * @see #observeOn(Scheduler, boolean)
-     * @see #delay(long, TimeUnit, Scheduler)
+     * @see #delay(long, TimeUnit, Scheduler, boolean)
      */
     @CheckReturnValue
     @NonNull

Diff for: src/main/java/io/reactivex/rxjava3/core/Observable.java

@@ -9793,6 +9793,11 @@ public final Observable<T> mergeWith(@NonNull CompletableSource other) {
      * asynchronous. If strict event ordering is required, consider using the {@link #observeOn(Scheduler, boolean)} overload.
      * <p>
      * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.png" alt="">
+     * <p>
+     * This operator keeps emitting as many signals as it can on the given Scheduler's Worker thread,
+     * which may result in a longer than expected occupation of this thread. In other terms,
+     * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
+     * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>You specify which {@link Scheduler} this operator will use.</dd>
@@ -9809,6 +9814,7 @@ public final Observable<T> mergeWith(@NonNull CompletableSource other) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler, boolean)
      * @see #observeOn(Scheduler, boolean, int)
+     * @see #delay(long, TimeUnit, Scheduler)
      */
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.CUSTOM)
@@ -9826,7 +9832,6 @@ public final Observable<T> observeOn(Scheduler scheduler) {
      * which may result in a longer than expected occupation of this thread. In other terms,
      * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
      * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
-     * <p>
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>You specify which {@link Scheduler} this operator will use.</dd>
@@ -9847,7 +9852,7 @@ public final Observable<T> observeOn(Scheduler scheduler) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler)
      * @see #observeOn(Scheduler, boolean, int)
-     * @see #delay(long, TimeUnit, Scheduler)
+     * @see #delay(long, TimeUnit, Scheduler, boolean)
      */
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.CUSTOM)
@@ -9865,7 +9870,6 @@ public final Observable<T> observeOn(Scheduler scheduler, boolean delayError) {
      * which may result in a longer than expected occupation of this thread. In other terms,
      * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
      * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
-     * <p>
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>You specify which {@link Scheduler} this operator will use.</dd>
@@ -9887,7 +9891,7 @@ public final Observable<T> observeOn(Scheduler scheduler, boolean delayError) {
      * @see #subscribeOn
      * @see #observeOn(Scheduler)
      * @see #observeOn(Scheduler, boolean)
-     * @see #delay(long, TimeUnit, Scheduler)
+     * @see #delay(long, TimeUnit, Scheduler, boolean)
      */
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.CUSTOM)

Diff for: src/main/java/io/reactivex/rxjava3/schedulers/Schedulers.java

@@ -317,6 +317,11 @@ public static Scheduler single() {
      * with a time delay close to each other may end up executing in different order than
      * the original schedule() call was issued. This limitation may be lifted in a future patch.
      * <p>
+     * The implementation of the Worker of this wrapper Scheduler is eager and will execute as many
+     * non-delayed tasks as it can, which may result in a longer than expected occupation of a
+     * thread of the given backing Executor. In other terms, it does not allow per-Runnable fairness
+     * in case the worker runs on a shared underlying thread of the Executor.
+     * <p>
      * Starting, stopping and restarting this scheduler is not supported (no-op) and the provided
      * executor's lifecycle must be managed externally:
      * <pre><code>
@@ -373,6 +378,11 @@ public static Scheduler from(@NonNull Executor executor) {
      * with a time delay close to each other may end up executing in different order than
      * the original schedule() call was issued. This limitation may be lifted in a future patch.
      * <p>
+     * The implementation of the Worker of this wrapper Scheduler is eager and will execute as many
+     * non-delayed tasks as it can, which may result in a longer than expected occupation of a
+     * thread of the given backing Executor. In other terms, it does not allow per-Runnable fairness
+     * in case the worker runs on a shared underlying thread of the Executor.
+     * <p>
      * Starting, stopping and restarting this scheduler is not supported (no-op) and the provided
      * executor's lifecycle must be managed externally:
      * <pre><code>