3.x: Schedulers.from vs. RejectedExecutionException (#7150)

Author: akarnokd

src/main/java/io/reactivex/rxjava3/schedulers/Schedulers.java

@@ -340,6 +340,16 @@ public static Scheduler single() {
      * }
      * </code></pre>
      * <p>
+     * Note that the provided {@code Executor} should avoid throwing a {@link RejectedExecutionException}
+     * (for example, by shutting it down prematurely or using a bounded-queue {@code ExecutorService})
+     * because such circumstances prevent RxJava from progressing flow-related activities correctly.
+     * If the {@link Executor#execute(Runnable)} or {@link ExecutorService#submit(Callable)} throws,
+     * the {@code RejectedExecutionException} is routed to the global error handler via
+     * {@link RxJavaPlugins#onError(Throwable)}. To avoid shutdown-reladed problems, it is recommended
+     * all flows using the returned {@code Scheduler} to be canceled/disposed before the underlying
+     * {@code Executor} is shut down. To avoid problems due to the {@code Executor} having a bounded-queue,
+     * it is recommended to rephrase the flow to utilize backpressure as the means to limit outstanding work.
+     * <p>
      * This type of scheduler is less sensitive to leaking {@link io.reactivex.rxjava3.core.Scheduler.Worker Scheduler.Worker} instances, although
      * not disposing a worker that has timed/delayed tasks not cancelled by other means may leak resources and/or
      * execute those tasks "unexpectedly".
@@ -404,6 +414,16 @@ public static Scheduler from(@NonNull Executor executor) {
      * }
      * </code></pre>
      * <p>
+     * Note that the provided {@code Executor} should avoid throwing a {@link RejectedExecutionException}
+     * (for example, by shutting it down prematurely or using a bounded-queue {@code ExecutorService})
+     * because such circumstances prevent RxJava from progressing flow-related activities correctly.
+     * If the {@link Executor#execute(Runnable)} or {@link ExecutorService#submit(Callable)} throws,
+     * the {@code RejectedExecutionException} is routed to the global error handler via
+     * {@link RxJavaPlugins#onError(Throwable)}. To avoid shutdown-reladed problems, it is recommended
+     * all flows using the returned {@code Scheduler} to be canceled/disposed before the underlying
+     * {@code Executor} is shut down. To avoid problems due to the {@code Executor} having a bounded-queue,
+     * it is recommended to rephrase the flow to utilize backpressure as the means to limit outstanding work.
+     * <p>
      * This type of scheduler is less sensitive to leaking {@link io.reactivex.rxjava3.core.Scheduler.Worker Scheduler.Worker} instances, although
      * not disposing a worker that has timed/delayed tasks not cancelled by other means may leak resources and/or
      * execute those tasks "unexpectedly".
@@ -474,6 +494,16 @@ public static Scheduler from(@NonNull Executor executor, boolean interruptibleWo
      * }
      * </code></pre>
      * <p>
+     * Note that the provided {@code Executor} should avoid throwing a {@link RejectedExecutionException}
+     * (for example, by shutting it down prematurely or using a bounded-queue {@code ExecutorService})
+     * because such circumstances prevent RxJava from progressing flow-related activities correctly.
+     * If the {@link Executor#execute(Runnable)} or {@link ExecutorService#submit(Callable)} throws,
+     * the {@code RejectedExecutionException} is routed to the global error handler via
+     * {@link RxJavaPlugins#onError(Throwable)}. To avoid shutdown-reladed problems, it is recommended
+     * all flows using the returned {@code Scheduler} to be canceled/disposed before the underlying
+     * {@code Executor} is shut down. To avoid problems due to the {@code Executor} having a bounded-queue,
+     * it is recommended to rephrase the flow to utilize backpressure as the means to limit outstanding work.
+     * <p>
      * This type of scheduler is less sensitive to leaking {@link io.reactivex.rxjava3.core.Scheduler.Worker Scheduler.Worker} instances, although
      * not disposing a worker that has timed/delayed tasks not cancelled by other means may leak resources and/or
      * execute those tasks "unexpectedly".