Debian Codegraph @

src/main/java/io/reactivex/rxjava3/operators/SimpleQueue.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.*;
17
18 /**
19 * A simplified interface for offering, polling and clearing a queue.
20 * <p>
21 * This interface does not define most of the {@link java.util.Collection}
22 * or {@link java.util.Queue} methods as the intended usage of {@code SimpleQueue}
23 * does not require support for iteration or introspection.
24 *
25 * @param <T> the value type to offer and poll, not null
26 * @since 3.1.1
27 */
28 public interface SimpleQueue<@NonNull T> {
29
30 /**
31 * Atomically enqueue a single value.
32 * @param value the value to enqueue, not null
33 * @return true if successful, false if the value was not enqueued
34 * likely due to reaching the queue capacity)
35 */
36 boolean offer(@NonNull T value);
37
38 /**
39 * Atomically enqueue two values.
40 * @param v1 the first value to enqueue, not null
41 * @param v2 the second value to enqueue, not null
42 * @return true if successful, false if the value was not enqueued
43 * likely due to reaching the queue capacity)
44 */
45 boolean offer(@NonNull T v1, @NonNull T v2);
46
47 /**
48 * Tries to dequeue a value (non-null) or returns null if
49 * the queue is empty.
50 * <p>
51 * If the producer uses {@link #offer(Object, Object)} and
52 * when polling in pairs, if the first poll() returns a non-null
53 * item, the second poll() is guaranteed to return a non-null item
54 * as well.
55 * @return the item or null to indicate an empty queue
56 * @throws Throwable if some pre-processing of the dequeued
57 * item (usually through fused functions) throws.
58 */
59 @Nullable
60 T poll() throws Throwable;
61
62 /**
63 * Returns true if the queue is empty.
64 * <p>
65 * Note however that due to potential fused functions in {@link #poll()}
66 * it is possible this method returns false but then poll() returns null
67 * because the fused function swallowed the available item(s).
68 * @return true if the queue is empty
69 */
70 boolean isEmpty();
71
72 /**
73 * Removes all enqueued items from this queue.
74 */
75 void clear();
76 }