View Javadoc
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  }