Debian Codegraph @

src/main/java/io/reactivex/rxjava3/operators/QueueFuseable.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
18 /**
19 * Represents a {@link SimpleQueue} plus the means and constants for requesting a fusion mode.
20 * @param <T> the value type returned by the SimpleQueue.poll()
21 * @since 3.1.1
22 */
23 public interface QueueFuseable<@NonNull T> extends SimpleQueue<T> {
24 /**
25 * Returned by the {@link #requestFusion(int)} if the upstream doesn't support
26 * the requested mode.
27 */
28 int NONE = 0;
29
30 /**
31 * Request a synchronous fusion mode and can be returned by {@link #requestFusion(int)}
32 * for an accepted mode.
33 * <p>
34 * In synchronous fusion, all upstream values are either already available or is generated
35 * when {@link #poll()} is called synchronously. When the {@link #poll()} returns null,
36 * that is the indication if a terminated stream.
37 * In this mode, the upstream won't call the onXXX methods and callers of
38 * {@link #poll()} should be prepared to catch exceptions. Note that {@link #poll()} has
39 * to be called sequentially (from within a serializing drain-loop).
40 */
41 int SYNC = 1;
42
43 /**
44 * Request an asynchronous fusion mode and can be returned by {@link #requestFusion(int)}
45 * for an accepted mode.
46 * <p>
47 * In asynchronous fusion, upstream values may become available to {@link #poll()} eventually.
48 * Upstream signals onError() and onComplete() as usual but onNext may not actually contain
49 * the upstream value but have {@code null} instead. Downstream should treat such onNext as indication
50 * that {@link #poll()} can be called. Note that {@link #poll()} has to be called sequentially
51 * (from within a serializing drain-loop). In addition, callers of {@link #poll()} should be
52 * prepared to catch exceptions.
53 */
54 int ASYNC = 2;
55
56 /**
57 * Request any of the {@link #SYNC} or {@link #ASYNC} modes.
58 */
59 int ANY = SYNC | ASYNC;
60
61 /**
62 * Used in binary or combination with the other constants as an input to {@link #requestFusion(int)}
63 * indicating that the {@link #poll()} will be called behind an asynchronous boundary and thus
64 * may change the non-trivial computation locations attached to the {@link #poll()} chain of
65 * fused operators.
66 * <p>
67 * For example, fusing map() and observeOn() may move the computation of the map's function over to
68 * the thread run after the observeOn(), which is generally unexpected.
69 */
70 int BOUNDARY = 4;
71
72 /**
73 * Request a fusion mode from the upstream.
74 * <p>
75 * This should be called before {@code onSubscribe} returns.
76 * <p>
77 * Calling this method multiple times or after {@code onSubscribe} finished is not allowed
78 * and may result in undefined behavior.
79 * <p>
80 * @param mode the requested fusion mode, allowed values are {@link #SYNC}, {@link #ASYNC},
81 * {@link #ANY} combined with {@link #BOUNDARY} (e.g., {@code requestFusion(SYNC | BOUNDARY)}).
82 * @return the established fusion mode: {@link #NONE}, {@link #SYNC}, {@link #ASYNC}.
83 */
84 int requestFusion(int mode);
85
86 }