0
# Threading
1

2
Advanced threading utilities including thread pools, schedulers, execution strategies, and concurrency primitives optimized for server applications and high-performance networking.
3

4
## Capabilities
5

6
### ThreadPool Interface
7

8
Core thread pool abstraction extending Executor with server-specific features.
9

10
```java { .api }
11
/**
12
 * Thread pool interface for server applications
13
 */
14
public interface ThreadPool extends Executor, LifeCycle {
15
    /** Wait for thread pool to terminate */
16
    void join() throws InterruptedException;
17
    
18
    /** Get total number of threads */
19
    int getThreads();
20
    
21
    /** Get number of idle threads */
22
    int getIdleThreads();
23
    
24
    /** Check if thread pool is low on threads */
25
    boolean isLowOnThreads();
26
    
27
    /** Sized thread pool interface */
28
    interface SizedThreadPool extends ThreadPool {
29
        int getMinThreads();
30
        int getMaxThreads();
31
        void setMinThreads(int threads);
32
        void setMaxThreads(int threads);
33
    }
34
}
35
```
36

37
### QueuedThreadPool
38

39
Main thread pool implementation with configurable sizing and queuing.
40

41
```java { .api }
42
/**
43
 * Queued thread pool implementation
44
 */
45
public class QueuedThreadPool extends ContainerLifeCycle implements ThreadPool.SizedThreadPool {
46
    /** Create thread pool with default settings */
47
    public QueuedThreadPool();
48
    
49
    /** Create thread pool with max threads */
50
    public QueuedThreadPool(int maxThreads);
51
    
52
    /** Create thread pool with min/max threads */
53
    public QueuedThreadPool(int maxThreads, int minThreads);
54
    
55
    /** Set minimum number of threads */
56
    public void setMinThreads(int minThreads);
57
    
58
    /** Set maximum number of threads */
59
    public void setMaxThreads(int maxThreads);
60
    
61
    /** Set idle timeout for threads */
62
    public void setIdleTimeout(int idleTimeout);
63
    
64
    /** Set thread name prefix */
65
    public void setName(String name);
66
    
67
    /** Set daemon thread flag */
68
    public void setDaemon(boolean daemon);
69
    
70
    /** Get queue size */
71
    public int getQueueSize();
72
    
73
    /** Get busy thread count */
74
    public int getBusyThreads();
75
}
76
```
77

78
**Usage Examples:**
79

80
```java
81
import org.eclipse.jetty.util.thread.QueuedThreadPool;
82

83
// Create and configure thread pool
84
QueuedThreadPool threadPool = new QueuedThreadPool();
85
threadPool.setMinThreads(5);
86
threadPool.setMaxThreads(50);
87
threadPool.setIdleTimeout(30000); // 30 seconds
88
threadPool.setName("MyApp");
89
threadPool.setDaemon(false);
90

91
// Start thread pool
92
threadPool.start();
93

94
// Submit tasks
95
threadPool.execute(() -> {
96
    System.out.println("Task running in: " + Thread.currentThread().getName());
97
});
98

99
// Monitor thread pool
100
System.out.println("Threads: " + threadPool.getThreads());
101
System.out.println("Idle: " + threadPool.getIdleThreads());
102
System.out.println("Busy: " + threadPool.getBusyThreads());
103
System.out.println("Queue: " + threadPool.getQueueSize());
104

105
// Shutdown
106
threadPool.stop();
107
```
108

109
### VirtualThreadPool
110

111
Virtual thread pool implementation for Java 19+ virtual threads.
112

113
```java { .api }
114
/**
115
 * Virtual thread pool implementation (Java 19+)
116
 */
117
public class VirtualThreadPool extends ContainerLifeCycle implements ThreadPool, TryExecutor {
118
    /** Create virtual thread pool */
119
    public VirtualThreadPool();
120
    
121
    /** Create virtual thread pool with name */
122
    public VirtualThreadPool(String name);
123
    
124
    /** Try to execute task immediately */
125
    public boolean tryExecute(Runnable task);
126
}
127
```
128

129
### Scheduler Interface
130

131
Task scheduling interface for delayed and recurring tasks.
132

133
```java { .api }
134
/**
135
 * Task scheduler interface
136
 */
137
public interface Scheduler extends LifeCycle {
138
    /** Schedule one-time task */
139
    Task schedule(Runnable task, long delay, TimeUnit unit);
140
    
141
    /** Schedule recurring task with fixed delay */
142
    Task scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit);
143
    
144
    /** Scheduled task interface */
145
    interface Task {
146
        boolean cancel();
147
        boolean isCancelled();
148
        boolean isDone();
149
    }
150
}
151
```
152

153
### Scheduler Implementations
154

155
```java { .api }
156
/**
157
 * ScheduledExecutorService-based scheduler
158
 */
159
public class ScheduledExecutorScheduler extends ContainerLifeCycle implements Scheduler {
160
    /** Create scheduler with default pool size */
161
    public ScheduledExecutorScheduler();
162
    
163
    /** Create scheduler with specific pool size */
164
    public ScheduledExecutorScheduler(String name, boolean daemon, int threads);
165
}
166

167
/**
168
 * Timer-based scheduler
169
 */
170
public class TimerScheduler extends ContainerLifeCycle implements Scheduler {
171
    /** Create timer scheduler */
172
    public TimerScheduler();
173
    
174
    /** Create timer scheduler with name and daemon flag */
175
    public TimerScheduler(String name, boolean daemon);
176
}
177
```
178

179
**Usage Examples:**
180

181
```java
182
import org.eclipse.jetty.util.thread.ScheduledExecutorScheduler;
183
import org.eclipse.jetty.util.thread.Scheduler;
184

185
// Create and start scheduler
186
Scheduler scheduler = new ScheduledExecutorScheduler("MyScheduler", true, 2);
187
scheduler.start();
188

189
// Schedule one-time task
190
Scheduler.Task task = scheduler.schedule(
191
    () -> System.out.println("Delayed task executed"),
192
    5, TimeUnit.SECONDS
193
);
194

195
// Schedule recurring task
196
Scheduler.Task recurring = scheduler.scheduleWithFixedDelay(
197
    () -> System.out.println("Recurring task: " + new Date()),
198
    1, 10, TimeUnit.SECONDS
199
);
200

201
// Cancel tasks
202
boolean cancelled = task.cancel();
203

204
// Shutdown
205
scheduler.stop();
206
```
207

208
### ExecutionStrategy
209

210
Thread execution strategies for different workloads.
211

212
```java { .api }
213
/**
214
 * Execution strategy interface
215
 */
216
public interface ExecutionStrategy extends LifeCycle {
217
    /** Produce and consume tasks */
218
    void produce();
219
    
220
    /** Dispatch execution */
221
    void dispatch();
222
    
223
    /** Producer interface for generating tasks */
224
    interface Producer {
225
        Runnable produce();
226
    }
227
}
228
```
229

230
### Concurrency Utilities
231

232
```java { .api }
233
/**
234
 * Auto-closeable lock implementation
235
 */
236
public class AutoLock implements Closeable {
237
    /** Create auto lock */
238
    public AutoLock();
239
    
240
    /** Acquire lock (use with try-with-resources) */
241
    public AutoLock lock();
242
    
243
    /** Try to acquire lock */
244
    public AutoLock tryLock();
245
    
246
    /** Check if locked */
247
    public boolean isLocked();
248
}
249

250
/**
251
 * Serialized task execution
252
 */
253
public class SerializedExecutor implements Executor {
254
    /** Create serialized executor */
255
    public SerializedExecutor(Executor executor);
256
}
257

258
/**
259
 * Reserved thread executor for low-latency tasks
260
 */
261
public class ReservedThreadExecutor extends AbstractLifeCycle implements TryExecutor {
262
    /** Create with thread pool and capacity */
263
    public ReservedThreadExecutor(Executor executor, int capacity);
264
    
265
    /** Set reservation capacity */
266
    public void setCapacity(int capacity);
267
    
268
    /** Get current capacity */
269
    public int getCapacity();
270
}
271
```
272

273
**Usage Examples:**
274

275
```java
276
import org.eclipse.jetty.util.thread.AutoLock;
277
import org.eclipse.jetty.util.thread.SerializedExecutor;
278
import org.eclipse.jetty.util.thread.ReservedThreadExecutor;
279

280
// Auto lock usage
281
AutoLock lock = new AutoLock();
282
try (AutoLock ignored = lock.lock()) {
283
    // Critical section
284
    sharedResource.modify();
285
} // Lock automatically released
286

287
// Serialized execution
288
Executor serialized = new SerializedExecutor(threadPool);
289
serialized.execute(task1); // These tasks will execute
290
serialized.execute(task2); // in submission order
291
serialized.execute(task3);
292

293
// Reserved threads for low-latency
294
ReservedThreadExecutor reserved = new ReservedThreadExecutor(threadPool, 2);
295
reserved.start();
296

297
// Try immediate execution (low-latency path)
298
boolean executed = reserved.tryExecute(() -> {
299
    // High-priority, low-latency task
300
});
301

302
if (!executed) {
303
    // Fall back to regular thread pool
304
    threadPool.execute(task);
305
}
306
```
307

308
## Performance Characteristics
309

310
- **QueuedThreadPool**: Dynamic thread creation/destruction based on load
311
- **VirtualThreadPool**: Millions of lightweight virtual threads (Java 19+)
312
- **ScheduledExecutorScheduler**: Precise timing with thread pool backing
313
- **ReservedThreadExecutor**: Ultra-low latency for critical tasks
314
- **SerializedExecutor**: Ordered execution with minimal overhead
315
- **AutoLock**: Zero-allocation lock with try-with-resources support
316

317
## Best Practices
318

319
1. **Use QueuedThreadPool** as default for most server applications
320
2. **Configure min/max threads** based on expected load
321
3. **Monitor thread pool metrics** (busy, idle, queue size)
322
4. **Use VirtualThreadPool** for I/O-heavy workloads on Java 19+
323
5. **Reserve threads** for critical, low-latency operations
324
6. **Serialize related tasks** to avoid synchronization overhead
325
7. **Use AutoLock** for clean, exception-safe locking patterns