Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

2.x: Add blockingSubscribe JavaDoc clarifications #5984

Merged
merged 1 commit into from
Apr 30, 2018
Merged

2.x: Add blockingSubscribe JavaDoc clarifications #5984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion src/main/java/io/reactivex/Flowable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5801,6 +5801,10 @@ public final Future<T> toFuture() {

/**
* Runs the source Flowable to a terminal event, ignoring any values and rethrowing any exception.
* <p>
* 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.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator consumes the source {@code Flowable} in an unbounded manner
Expand All @@ -5809,6 +5813,9 @@ public final Future<T> toFuture() {
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
* @since 2.0
* @see #blockingSubscribe(Consumer)
* @see #blockingSubscribe(Consumer, Consumer)
* @see #blockingSubscribe(Consumer, Consumer, Action)
*/
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@SchedulerSupport(SchedulerSupport.NONE)
Expand All @@ -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.
* <p>
* 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.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator consumes the source {@code Flowable} in an unbounded manner
Expand All @@ -5831,6 +5844,8 @@ public final void blockingSubscribe() {
* </dl>
* @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)
Expand All @@ -5840,6 +5855,10 @@ public final void blockingSubscribe(Consumer<? super T> onNext) {

/**
* Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
* <p>
* 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.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator consumes the source {@code Flowable} in an unbounded manner
Expand All @@ -5850,6 +5869,7 @@ public final void blockingSubscribe(Consumer<? super T> 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)
Expand All @@ -5860,6 +5880,10 @@ public final void blockingSubscribe(Consumer<? super T> onNext, Consumer<? super

/**
* Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
* <p>
* 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.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator consumes the source {@code Flowable} in an unbounded manner
Expand All @@ -5879,7 +5903,13 @@ public final void blockingSubscribe(Consumer<? super T> onNext, Consumer<? super
}

/**
* Subscribes to the source and calls the Subscriber methods <strong>on the current thread</strong>.
* Subscribes to the source and calls the {@link Subscriber} methods <strong>on the current thread</strong>.
* <p>
* 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.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The supplied {@code Subscriber} determines how backpressure is applied.</dd>
Expand Down
40 changes: 35 additions & 5 deletions src/main/java/io/reactivex/Observable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5314,11 +5314,18 @@ public final Future<T> toFuture() {
* Runs the source observable to a terminal event, ignoring any values and rethrowing any exception.
* <p>
* <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.0.png" alt="">
* <p>
* 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.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
* @since 2.0
* @see #blockingSubscribe(Consumer)
* @see #blockingSubscribe(Consumer, Consumer)
* @see #blockingSubscribe(Consumer, Consumer, Action)
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe() {
Expand All @@ -5330,15 +5337,23 @@ public final void blockingSubscribe() {
* <p>
* <img width="640" height="393" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.1.png" alt="">
* <p>
* 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.
* <p>
* 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.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
* @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<? super T> onNext) {
Expand All @@ -5349,13 +5364,18 @@ public final void blockingSubscribe(Consumer<? super T> onNext) {
* Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
* <p>
* <img width="640" height="396" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.2.png" alt="">
* <p>
* 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.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
* @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<? super T> onNext, Consumer<? super Throwable> onError) {
Expand All @@ -5367,6 +5387,10 @@ public final void blockingSubscribe(Consumer<? super T> onNext, Consumer<? super
* Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
* <p>
* <img width="640" height="394" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.png" alt="">
* <p>
* 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.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -5382,18 +5406,24 @@ public final void blockingSubscribe(Consumer<? super T> onNext, Consumer<? super
}

/**
* Subscribes to the source and calls the Observer methods <strong>on the current thread</strong>.
* Subscribes to the source and calls the {@link Observer} methods <strong>on the current thread</strong>.
* <p>
* 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.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
* 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<? super T> subscriber) {
ObservableBlockingSubscribe.subscribe(this, subscriber);
public final void blockingSubscribe(Observer<? super T> observer) {
ObservableBlockingSubscribe.subscribe(this, observer);
}

/**
Expand Down