Debian Codegraph @

src/main/java/io/reactivex/rxjava3/operators/QueueDisposable.java

raw
1 /*
2 * Copyright (c) 2016-present, RxJava Contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
11 * the License for the specific language governing permissions and limitations under the License.
12 */
13
14 package io.reactivex.rxjava3.operators;
15
16 import io.reactivex.rxjava3.annotations.NonNull;
17 import io.reactivex.rxjava3.disposables.Disposable;
18
19 /**
20 * An interface extending {@link SimpleQueue} and {@link Disposable} and allows negotiating
21 * the fusion mode between subsequent operators of the {@link io.reactivex.rxjava3.core.Observable Observable} base reactive type.
22 * <p>
23 * The negotiation happens in subscription time when the upstream
24 * calls the {@code onSubscribe} with an instance of this interface. The
25 * downstream has then the obligation to call {@link #requestFusion(int)}
26 * with the appropriate mode before calling {@code request()}.
27 * <p>
28 * In <b>synchronous fusion</b>, all upstream values are either already available or is generated
29 * when {@link #poll()} is called synchronously. When the {@link #poll()} returns {@code null},
30 * that is the indication if a terminated stream. In this mode, the upstream won't call the onXXX methods.
31 * <p>
32 * In <b>asynchronous fusion</b>, upstream values may become available to {@link #poll()} eventually.
33 * Upstream signals {@code onError()} and {@code onComplete()} as usual, however,
34 * {@code onNext} will be called with {@code null} instead of the actual value.
35 * Downstream should treat such onNext as indication that {@link #poll()} can be called.
36 * <p>
37 * The general rules for consuming the {@link SimpleQueue} interface:
38 * <ul>
39 * <li> {@link #poll()} and {@link #clear()} has to be called sequentially (from within a serializing drain-loop).</li>
40 * <li>In addition, callers of {@link #poll()} should be prepared to catch exceptions.</li>
41 * <li>Due to how computation attaches to the {@link #poll()}, {@link #poll()} may return
42 * {@code null} even if a preceding {@link #isEmpty()} returned false.</li>
43 * </ul>
44 * <p>
45 * Implementations should only allow calling the following methods and the rest of the
46 * {@link SimpleQueue} interface methods should throw {@link UnsupportedOperationException}:
47 * <ul>
48 * <li>{@link #poll()}</li>
49 * <li>{@link #isEmpty()}</li>
50 * <li>{@link #clear()}</li>
51 * </ul>
52 * @param <T> the value type transmitted through the queue
53 * @see QueueSubscription
54 * @since 3.1.1
55 */
56 public interface QueueDisposable<@NonNull T> extends QueueFuseable<T>, Disposable {
57 }