1 /*
2 * Copyright 2025 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.util.concurrent;
17
18 import io.netty.util.IntSupplier;
19 import io.netty.util.IntConsumer;
20
21 /**
22 * A multi-producer (concurrent and thread-safe {@code offer} and {@code fill}),
23 * single-consumer (single-threaded {@code poll} and {@code drain}) queue of primitive integers.
24 */
25 public interface MpscIntQueue {
26
27 /**
28 * Offer the given value to the queue. This will throw an exception if the given value is the "empty" value.
29 * @param value The value to add to the queue.
30 * @return {@code true} if the value was added to the queue,
31 * or {@code false} if the value could not be added because the queue is full.
32 */
33 boolean offer(int value);
34
35 /**
36 * Remove and return the next value from the queue, or return the "empty" value if the queue is empty.
37 * @return The next value or the "empty" value.
38 */
39 int poll();
40
41 /**
42 * Remove up to the given limit of elements from the queue, and pass them to the consumer in order.
43 * @param limit The maximum number of elements to dequeue.
44 * @param consumer The consumer to pass the removed elements to.
45 * @return The actual number of elements removed.
46 */
47 int drain(int limit, IntConsumer consumer);
48
49 /**
50 * Add up to the given limit of elements to this queue, from the given supplier.
51 * @param limit The maximum number of elements to enqueue.
52 * @param supplier The supplier to obtain the elements from.
53 * @return The actual number of elements added.
54 */
55 int fill(int limit, IntSupplier supplier);
56
57 /**
58 * Query if the queue is empty or not.
59 * <p>
60 * This method is inherently racy and the result may be out of date by the time the method returns.
61 * @return {@code true} if the queue was observed to be empty, otherwise {@code false.
62 */
63 boolean isEmpty();
64
65 /**
66 * Query the number of elements currently in the queue.
67 * <p>
68 * This method is inherently racy and the result may be out of date by the time the method returns.
69 * @return An estimate of the number of elements observed in the queue.
70 */
71 int size();
72 }