0
# Resource Management
1

2
The resource management system provides efficient allocation and sharing of Netty resources including EventLoopGroups, ByteBuf allocators, and connection pools. This system optimizes memory usage and performance across both transport and HTTP layers.
3

4
## Capabilities
5

6
### SharedGroupFactory
7

8
Manages shared Netty EventLoopGroup instances that can be used by both transport and HTTP layers for efficient resource utilization.
9

10
```java { .api }
11
/**
12
 * Creates and manages shared EventLoopGroup instances for transport and HTTP
13
 * Provides resource sharing when configured, or dedicated groups when needed
14
 */
15
public final class SharedGroupFactory {
16
    /**
17
     * Creates factory with specified settings
18
     * @param settings Configuration settings for group management
19
     */
20
    public SharedGroupFactory(Settings settings);
21
    
22
    /**
23
     * Gets configuration settings used by this factory
24
     * @return Settings object used for initialization
25
     */
26
    public Settings getSettings();
27
    
28
    /**
29
     * Gets the configured worker count for transport operations
30
     * @return Number of worker threads for transport layer
31
     */
32
    public int getTransportWorkerCount();
33
    
34
    /**
35
     * Gets EventLoopGroup for transport layer operations
36
     * May be shared with HTTP layer depending on configuration
37
     * @return SharedGroup for transport operations
38
     */
39
    public SharedGroup getTransportGroup();
40
    
41
    /**
42
     * Gets EventLoopGroup for HTTP layer operations  
43
     * May be shared with transport layer or dedicated depending on configuration
44
     * @return SharedGroup for HTTP operations
45
     */
46
    public SharedGroup getHttpGroup();
47
}
48
```
49

50
**Resource Sharing Behavior:**
51

52
```java
53
// Factory determines sharing based on HTTP worker count setting
54
Settings settings = Settings.builder()
55
    .put("http.netty.worker_count", 0) // 0 = shared, >0 = dedicated
56
    .put("transport.netty.worker_count", 4)
57
    .build();
58

59
SharedGroupFactory factory = new SharedGroupFactory(settings);
60

61
// With http.netty.worker_count = 0, both return same group
62
SharedGroup transportGroup = factory.getTransportGroup();
63
SharedGroup httpGroup = factory.getHttpGroup(); // Same as transport
64

65
// With http.netty.worker_count > 0, returns different groups
66
Settings dedicatedSettings = Settings.builder()
67
    .put("http.netty.worker_count", 2) // Dedicated HTTP workers
68
    .build();
69

70
SharedGroupFactory dedicatedFactory = new SharedGroupFactory(dedicatedSettings);
71
SharedGroup dedicatedTransport = dedicatedFactory.getTransportGroup(); 
72
SharedGroup dedicatedHttp = dedicatedFactory.getHttpGroup(); // Different group
73
```
74

75
### SharedGroup Interface
76

77
Wrapper interface for Netty EventLoopGroup providing resource management and lifecycle control.
78

79
```java { .api }
80
/**
81
 * Wrapper for Netty EventLoopGroup with reference counting and lifecycle management
82
 * Allows safe sharing of EventLoopGroup instances across multiple components
83
 */
84
public interface SharedGroup extends Releasable {
85
    /**
86
     * Gets the underlying Netty EventLoopGroup
87
     * @return EventLoopGroup for Netty channel operations
88
     */
89
    EventLoopGroup getEventLoopGroup();
90
    
91
    /**
92
     * Increments reference count for this shared group
93
     * Must be paired with corresponding release() call
94
     */
95
    void acquire();
96
    
97
    /**
98
     * Decrements reference count and releases resources when count reaches zero
99
     * EventLoopGroup is shutdown when no more references exist
100
     */
101
    void release();
102
    
103
    /**
104
     * Gets current reference count
105
     * @return Number of active references to this group
106
     */
107
    int getRefCount();
108
}
109
```
110

111
**Usage Example:**
112

113
```java
114
SharedGroupFactory factory = new SharedGroupFactory(settings);
115
SharedGroup transportGroup = factory.getTransportGroup();
116

117
// Acquire reference before using in component
118
transportGroup.acquire();
119

120
// Use EventLoopGroup for Netty operations
121
EventLoopGroup eventLoop = transportGroup.getEventLoopGroup();
122
Bootstrap bootstrap = new Bootstrap()
123
    .group(eventLoop)
124
    .channel(NioSocketChannel.class);
125

126
// Always release when done
127
transportGroup.release();
128
```
129

130
### NettyAllocator
131

132
Provides optimized ByteBuf allocation strategies based on JVM configuration and system resources.
133

134
```java { .api }
135
/**
136
 * Manages Netty ByteBuf allocation with optimized strategies
137
 * Configures allocator based on JVM heap size, GC settings, and system properties
138
 */
139
public class NettyAllocator {
140
    /**
141
     * Gets configured ByteBuf allocator instance
142
     * Returns either pooled or unpooled allocator based on system configuration
143
     * @return ByteBufAllocator for creating buffers
144
     */
145
    public static ByteBufAllocator getAllocator();
146
    
147
    /**
148
     * Gets suggested maximum allocation size for single buffer
149
     * Based on heap size and allocation strategy
150
     * @return Maximum recommended buffer size in bytes
151
     */
152
    public static long suggestedMaxAllocationSize();
153
    
154
    /**
155
     * Gets human-readable description of allocator configuration
156
     * Includes allocator type, max allocation size, and configuration factors
157
     * @return Description string for logging and diagnostics
158
     */
159
    public static String getAllocatorDescription();
160
    
161
    /**
162
     * Logs allocator description to logger if not already logged
163
     * Thread-safe single logging of allocator configuration at startup
164
     */
165
    public static void logAllocatorDescriptionIfNeeded();
166
    
167
    /**
168
     * Gets optimal Netty channel type based on allocator configuration
169
     * Returns different channel types for direct/heap buffer strategies
170
     * @return Channel class for client connections
171
     */
172
    public static Class<? extends Channel> getChannelType();
173
    
174
    /**
175
     * Gets optimal Netty server channel type based on allocator configuration
176
     * Returns different server channel types for direct/heap buffer strategies
177
     * @return ServerChannel class for server listening
178
     */
179
    public static Class<? extends ServerChannel> getServerChannelType();
180
}
181
```
182

183
**Allocator Selection Logic:**
184

185
```java
186
// NettyAllocator automatically selects strategy based on:
187

188
// 1. System property override
189
System.setProperty("es.use_unpooled_allocator", "true"); // Forces unpooled
190

191
// 2. Heap size and GC type analysis
192
long heapSize = JvmInfo.jvmInfo().getMem().getHeapMax().getBytes();
193
boolean g1gcEnabled = Boolean.parseBoolean(JvmInfo.jvmInfo().useG1GC());
194

195
// 3. Automatic selection
196
ByteBufAllocator allocator = NettyAllocator.getAllocator();
197
long maxAllocation = NettyAllocator.suggestedMaxAllocationSize();
198

199
// Example configurations:
200
// Small heap (<1GB): UnpooledByteBufAllocator, 1MB max allocation
201
// Large heap + G1GC: PooledByteBufAllocator, 8MB max allocation  
202
// Large heap + other GC: PooledByteBufAllocator, 1MB max allocation
203
```
204

205
### ByteBuf Management Utilities
206

207
Utility classes for efficient ByteBuf handling and size management.
208

209
```java { .api }
210
/**
211
 * Netty pipeline handler for ByteBuf size management and optimization
212
 * Handles buffer sizing predictions and memory usage optimization
213
 */
214
public class NettyByteBufSizer extends MessageToMessageDecoder<ByteBuf> {
215
    // Automatically handles ByteBuf sizing and optimization
216
    // Adjusts buffer allocation strategies based on usage patterns
217
}
218
```
219

220
### Memory Usage Optimization
221

222
The resource management system implements several optimization strategies:
223

224
**Adaptive Buffer Sizing**: Netty's AdaptiveRecvByteBufAllocator adjusts buffer sizes based on actual data patterns
225

226
**Pooled Allocation**: Uses PooledByteBufAllocator for large heap JVMs to reduce GC pressure
227

228
**Composite Buffers**: Efficiently handles large responses by composing multiple smaller buffers
229

230
**Reference Counting**: Proper ByteBuf lifecycle management prevents memory leaks
231

232
**Chunk Size Tuning**: Optimizes chunk and page sizes based on heap size and GC characteristics
233

234
**Direct Memory Management**: Uses direct buffers for network I/O to avoid copying
235

236
## Resource Configuration Examples
237

238
### Shared Resource Configuration
239

240
```java
241
// Configure shared EventLoopGroup between transport and HTTP
242
Settings sharedConfig = Settings.builder()
243
    .put("transport.netty.worker_count", 8) // Transport workers
244
    .put("http.netty.worker_count", 0) // Share with transport (default)
245
    .put("transport.netty.boss_count", 1) // Connection acceptance
246
    .build();
247

248
SharedGroupFactory sharedFactory = new SharedGroupFactory(sharedConfig);
249
// Both transport and HTTP use same EventLoopGroup
250
```
251

252
### Dedicated Resource Configuration
253

254
```java
255
// Configure dedicated EventLoopGroups for transport and HTTP
256
Settings dedicatedConfig = Settings.builder()
257
    .put("transport.netty.worker_count", 6) // Transport workers
258
    .put("http.netty.worker_count", 4) // Dedicated HTTP workers
259
    .put("transport.netty.boss_count", 1) // Transport boss threads
260
    .build();
261

262
SharedGroupFactory dedicatedFactory = new SharedGroupFactory(dedicatedConfig);
263
// Transport and HTTP use separate EventLoopGroups
264
```
265

266
### Buffer Allocation Configuration
267

268
```java
269
// System properties affecting buffer allocation
270
System.setProperty("es.use_unpooled_allocator", "false"); // Use pooled (default)
271
System.setProperty("es.unsafe.use_netty_default_allocator", "false"); // Use ES tuning
272
System.setProperty("es.unsafe.use_netty_default_chunk_and_page_size", "false"); // Use ES sizing
273

274
// Get optimized allocator
275
ByteBufAllocator allocator = NettyAllocator.getAllocator();
276
String description = NettyAllocator.getAllocatorDescription();
277
long maxSize = NettyAllocator.suggestedMaxAllocationSize();
278

279
// Create buffers with optimal settings
280
ByteBuf buffer = allocator.buffer(); // Default size
281
ByteBuf directBuffer = allocator.directBuffer(1024); // Specific size
282
CompositeByteBuf composite = allocator.compositeBuffer(); // Composite buffer
283
```
284

285
## Integration with Elasticsearch
286

287
The resource management system integrates with Elasticsearch through:
288

289
1. **Settings System**: Configuration via elasticsearch.yml and cluster settings
290

291
2. **Node Lifecycle**: Proper startup and shutdown of shared resources  
292

293
3. **Circuit Breaker Integration**: Respects memory circuit breakers for allocation limits
294

295
4. **Monitoring Integration**: Provides metrics on buffer usage and EventLoopGroup utilization
296

297
5. **JVM Integration**: Adapts allocation strategies based on JVM configuration
298

299
6. **Plugin Coordination**: Ensures proper resource sharing between plugin components
300

301
The resource management system ensures efficient utilization of system resources while maintaining the performance characteristics required for high-throughput Elasticsearch deployments.