From a388fe7224926986c5a3a11a38169747102e84e1 Mon Sep 17 00:00:00 2001 From: akarnokd Date: Sun, 29 Apr 2018 22:57:13 +0200 Subject: [PATCH] 2.x: Add blockingSubscribe JavaDoc clarifications --- src/main/java/io/reactivex/Flowable.java | 32 ++++++++++++++++- src/main/java/io/reactivex/Observable.java | 40 +++++++++++++++++++--- 2 files changed, 66 insertions(+), 6 deletions(-) diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java index 840c87804c..800cfa5ea5 100644 --- a/src/main/java/io/reactivex/Flowable.java +++ b/src/main/java/io/reactivex/Flowable.java @@ -5801,6 +5801,10 @@ public final Future toFuture() { /** * Runs the source Flowable to a terminal event, ignoring any values and rethrowing any exception. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Backpressure:
*
The operator consumes the source {@code Flowable} in an unbounded manner @@ -5809,6 +5813,9 @@ public final Future toFuture() { *
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
*
* @since 2.0 + * @see #blockingSubscribe(Consumer) + * @see #blockingSubscribe(Consumer, Consumer) + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @SchedulerSupport(SchedulerSupport.NONE) @@ -5822,6 +5829,12 @@ public final void blockingSubscribe() { * If the Flowable emits an error, it is wrapped into an * {@link io.reactivex.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} * and routed to the RxJavaPlugins.onError handler. + * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)} + * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Backpressure:
*
The operator consumes the source {@code Flowable} in an unbounded manner @@ -5831,6 +5844,8 @@ public final void blockingSubscribe() { *
* @param onNext the callback action for each source value * @since 2.0 + * @see #blockingSubscribe(Consumer, Consumer) + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @SchedulerSupport(SchedulerSupport.NONE) @@ -5840,6 +5855,10 @@ public final void blockingSubscribe(Consumer onNext) { /** * Subscribes to the source and calls the given callbacks on the current thread. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Backpressure:
*
The operator consumes the source {@code Flowable} in an unbounded manner @@ -5850,6 +5869,7 @@ public final void blockingSubscribe(Consumer onNext) { * @param onNext the callback action for each source value * @param onError the callback action for an error event * @since 2.0 + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @SchedulerSupport(SchedulerSupport.NONE) @@ -5860,6 +5880,10 @@ public final void blockingSubscribe(Consumer onNext, Consumeron the current thread. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Backpressure:
*
The operator consumes the source {@code Flowable} in an unbounded manner @@ -5879,7 +5903,13 @@ public final void blockingSubscribe(Consumer onNext, Consumeron the current thread. + * Subscribes to the source and calls the {@link Subscriber} methods on the current thread. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally, with an error or the {@code Subscriber} cancels the {@link Subscription} it receives via + * {@link Subscriber#onSubscribe(Subscription)}. + * Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Backpressure:
*
The supplied {@code Subscriber} determines how backpressure is applied.
diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java index ad60243113..2c32920c2e 100644 --- a/src/main/java/io/reactivex/Observable.java +++ b/src/main/java/io/reactivex/Observable.java @@ -5314,11 +5314,18 @@ public final Future toFuture() { * Runs the source observable to a terminal event, ignoring any values and rethrowing any exception. *

* + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Scheduler:
*
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
*
* @since 2.0 + * @see #blockingSubscribe(Consumer) + * @see #blockingSubscribe(Consumer, Consumer) + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @SchedulerSupport(SchedulerSupport.NONE) public final void blockingSubscribe() { @@ -5330,15 +5337,23 @@ public final void blockingSubscribe() { *

* *

- * If the Observable emits an error, it is wrapped into an + * If the {@code Observable} emits an error, it is wrapped into an * {@link io.reactivex.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} * and routed to the RxJavaPlugins.onError handler. + * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)} + * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Scheduler:
*
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
*
* @param onNext the callback action for each source value * @since 2.0 + * @see #blockingSubscribe(Consumer, Consumer) + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @SchedulerSupport(SchedulerSupport.NONE) public final void blockingSubscribe(Consumer onNext) { @@ -5349,6 +5364,10 @@ public final void blockingSubscribe(Consumer onNext) { * Subscribes to the source and calls the given callbacks on the current thread. *

* + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Scheduler:
*
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
@@ -5356,6 +5375,7 @@ public final void blockingSubscribe(Consumer onNext) { * @param onNext the callback action for each source value * @param onError the callback action for an error event * @since 2.0 + * @see #blockingSubscribe(Consumer, Consumer, Action) */ @SchedulerSupport(SchedulerSupport.NONE) public final void blockingSubscribe(Consumer onNext, Consumer onError) { @@ -5367,6 +5387,10 @@ public final void blockingSubscribe(Consumer onNext, Consumeron the current thread. *

* + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally or with an error. Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Scheduler:
*
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
@@ -5382,18 +5406,24 @@ public final void blockingSubscribe(Consumer onNext, Consumeron the current thread. + * Subscribes to the source and calls the {@link Observer} methods on the current thread. + *

+ * Note that calling this method will block the caller thread until the upstream terminates + * normally, with an error or the {@code Observer} disposes the {@link Disposable} it receives via + * {@link Observer#onSubscribe(Disposable)}. + * Therefore, calling this method from special threads such as the + * Android Main Thread or the Swing Event Dispatch Thread is not recommended. *

*
Scheduler:
*
{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
*
* The a dispose() call is composed through. - * @param subscriber the subscriber to forward events and calls to in the current thread + * @param observer the {@code Observer} instance to forward events and calls to in the current thread * @since 2.0 */ @SchedulerSupport(SchedulerSupport.NONE) - public final void blockingSubscribe(Observer subscriber) { - ObservableBlockingSubscribe.subscribe(this, subscriber); + public final void blockingSubscribe(Observer observer) { + ObservableBlockingSubscribe.subscribe(this, observer); } /**