1 /*
2 * Copyright 2012 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.netty5.channel;
17
18 import io.netty5.buffer.api.Buffer;
19 import io.netty5.buffer.api.BufferAllocator;
20
21 import java.util.function.Predicate;
22
23 /**
24 * Allocates a new receive buffer whose capacity is probably large enough to read all inbound data and small enough
25 * not to waste its space.
26 */
27 public interface RecvBufferAllocator {
28 /**
29 * Creates a new handle. The handle provides the actual operations and keeps the internal information which is
30 * required for predicting an optimal buffer capacity.
31 */
32 Handle newHandle();
33
34 interface Handle {
35 /**
36 * Creates a new receive buffer whose capacity is probably large enough to read all inbound data and small
37 * enough not to waste its space.
38 */
39 Buffer allocate(BufferAllocator alloc);
40
41 /**
42 * Similar to {@link #allocate(BufferAllocator)} except that it does not allocate anything but just tells the
43 * capacity.
44 */
45 int guess();
46
47 /**
48 * Reset any counters that have accumulated and recommend how many messages/bytes should be read for the next
49 * read loop.
50 * <p>
51 * This may be used by {@link #continueReading(boolean)} to determine if the read operation should complete.
52 * </p>
53 * This is only ever a hint and may be ignored by the implementation.
54 */
55 void reset();
56
57 /**
58 * Increment the number of messages that have been read for the current read loop.
59 *
60 * @param numMessages The amount to increment by.
61 */
62 void incMessagesRead(int numMessages);
63
64 /**
65 * Set the bytes that have been read for the last read operation.
66 * This may be used to increment the number of bytes that have been read.
67 *
68 * @param bytes The number of bytes from the previous read operation. This may be negative if an read error
69 * occurs. If a negative value is seen it is expected to be return on the next call to
70 * {@link #lastBytesRead()}. A negative value will signal a termination condition enforced
71 * externally to this class and is not required to be enforced in
72 * {@link #continueReading(boolean)}.
73 */
74 void lastBytesRead(int bytes);
75
76 /**
77 * Get the amount of bytes for the previous read operation.
78 *
79 * @return The amount of bytes for the previous read operation.
80 */
81 int lastBytesRead();
82
83 /**
84 * Set how many bytes the read operation will (or did) attempt to read.
85 *
86 * @param bytes How many bytes the read operation will (or did) attempt to read.
87 */
88 void attemptedBytesRead(int bytes);
89
90 /**
91 * Get how many bytes the read operation will (or did) attempt to read.
92 *
93 * @return How many bytes the read operation will (or did) attempt to read.
94 */
95 int attemptedBytesRead();
96
97 /**
98 * Determine if the current read loop should continue.
99 *
100 * @param autoRead {@çode true} if autoread is used, {@code false} otherwise.
101 * @return {@code true} if the read loop should continue reading. {@code false}
102 * if the read loop is complete.
103 */
104 boolean continueReading(boolean autoRead);
105
106 /**
107 * Same as {@link Handle#continueReading(boolean)} except "more data" is determined by the supplier parameter.
108 *
109 * @param autoRead {@code true} if autoread is used, {@code false} otherwise.
110 * @param maybeMoreDataPredicate A Predicate that determines if there maybe more data to read.
111 * @return {@code true} if the read loop should continue reading. {@code false} if the
112 * read loop is complete.
113 */
114 boolean continueReading(boolean autoRead, Predicate<Handle> maybeMoreDataPredicate);
115
116 /**
117 * The read has completed.
118 */
119 void readComplete();
120 }
121 }