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.netty.buffer;
17
18 /**
19 * Implementations are responsible to allocate buffers. Implementations of this interface are expected to be
20 * thread-safe.
21 */
22 public interface ByteBufAllocator {
23
24 ByteBufAllocator DEFAULT = ByteBufUtil.DEFAULT_ALLOCATOR;
25
26 /**
27 * Allocate a {@link ByteBuf}. If it is a direct or heap buffer
28 * depends on the actual implementation.
29 */
30 ByteBuf buffer();
31
32 /**
33 * Allocate a {@link ByteBuf} with the given initial capacity.
34 * If it is a direct or heap buffer depends on the actual implementation.
35 */
36 ByteBuf buffer(int initialCapacity);
37
38 /**
39 * Allocate a {@link ByteBuf} with the given initial capacity and the given
40 * maximal capacity. If it is a direct or heap buffer depends on the actual
41 * implementation.
42 */
43 ByteBuf buffer(int initialCapacity, int maxCapacity);
44
45 /**
46 * Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
47 */
48 ByteBuf ioBuffer();
49
50 /**
51 * Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
52 */
53 ByteBuf ioBuffer(int initialCapacity);
54
55 /**
56 * Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
57 */
58 ByteBuf ioBuffer(int initialCapacity, int maxCapacity);
59
60 /**
61 * Allocate a heap {@link ByteBuf}.
62 */
63 ByteBuf heapBuffer();
64
65 /**
66 * Allocate a heap {@link ByteBuf} with the given initial capacity.
67 */
68 ByteBuf heapBuffer(int initialCapacity);
69
70 /**
71 * Allocate a heap {@link ByteBuf} with the given initial capacity and the given
72 * maximal capacity.
73 */
74 ByteBuf heapBuffer(int initialCapacity, int maxCapacity);
75
76 /**
77 * Allocate a direct {@link ByteBuf}.
78 */
79 ByteBuf directBuffer();
80
81 /**
82 * Allocate a direct {@link ByteBuf} with the given initial capacity.
83 */
84 ByteBuf directBuffer(int initialCapacity);
85
86 /**
87 * Allocate a direct {@link ByteBuf} with the given initial capacity and the given
88 * maximal capacity.
89 */
90 ByteBuf directBuffer(int initialCapacity, int maxCapacity);
91
92 /**
93 * Allocate a {@link CompositeByteBuf}.
94 * If it is a direct or heap buffer depends on the actual implementation.
95 */
96 CompositeByteBuf compositeBuffer();
97
98 /**
99 * Allocate a {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
100 * If it is a direct or heap buffer depends on the actual implementation.
101 */
102 CompositeByteBuf compositeBuffer(int maxNumComponents);
103
104 /**
105 * Allocate a heap {@link CompositeByteBuf}.
106 */
107 CompositeByteBuf compositeHeapBuffer();
108
109 /**
110 * Allocate a heap {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
111 */
112 CompositeByteBuf compositeHeapBuffer(int maxNumComponents);
113
114 /**
115 * Allocate a direct {@link CompositeByteBuf}.
116 */
117 CompositeByteBuf compositeDirectBuffer();
118
119 /**
120 * Allocate a direct {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
121 */
122 CompositeByteBuf compositeDirectBuffer(int maxNumComponents);
123
124 /**
125 * Returns {@code true} if direct {@link ByteBuf}'s are pooled
126 */
127 boolean isDirectBufferPooled();
128
129 /**
130 * Calculate the new capacity of a {@link ByteBuf} that is used when a {@link ByteBuf} needs to expand by the
131 * {@code minNewCapacity} with {@code maxCapacity} as upper-bound.
132 */
133 int calculateNewCapacity(int minNewCapacity, int maxCapacity);
134 }