Skip to content

Commit 3d8fa01

Browse files
yybmionyybmion
committed
feat: Implement Thread-Pool Executor pattern
- Add implementation of Thread-Pool Executor pattern using hotel front desk example - Include unit tests - Create detailed README with pattern explanation and examples - Add Java source code with appropriate Javadoc comments Closes iluwatar#3226
1 parent f8f33f5 commit 3d8fa01

File tree

13 files changed

+1036
-0
lines changed

13 files changed

+1036
-0
lines changed

‎pom.xml

+1
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,7 @@
231231
<module>table-module</module>
232232
<module>template-method</module>
233233
<module>templateview</module>
234+
<module>thread-pool-executor</module>
234235
<module>throttling</module>
235236
<module>tolerant-reader</module>
236237
<module>trampoline</module>

‎thread-pool-executor/README.md

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: "Thread-Pool Executor Pattern in Java: Efficient Concurrent Task Management"
3+
shortTitle: Thread-Pool Executor
4+
description: "Learn the Thread-Pool Executor pattern in Java with practical examples, class
5+
diagrams, and implementation details. Understand how to manage concurrent tasks efficiently,
6+
improving resource utilization and application performance."
7+
category: Concurrency
8+
language: en
9+
tag:
10+
11+
- Performance
12+
- Resource Management
13+
- Concurrency
14+
- Multithreading
15+
- Scalability
16+
17+
---
18+
19+
## Intent of Thread-Pool Executor Design Pattern
20+
21+
The Thread-Pool Executor pattern maintains a pool of worker threads to execute tasks concurrently,
22+
optimizing resource usage by reusing existing threads instead of creating new ones for each task.
23+
24+
## Detailed Explanation of Thread-Pool Executor Pattern with Real-World Examples
25+
26+
### Real-world example
27+
28+
> Imagine a busy airport security checkpoint where instead of opening a new lane for each traveler,
29+
> a fixed number of security lanes (threads) are open to process all passengers. Each security
30+
> officer (thread) processes one passenger (task) at a time, and when finished, immediately calls the
31+
> next passenger in line. During peak travel times, passengers wait in a queue, but the system is much
32+
> more efficient than trying to open a new security lane for each individual traveler. The airport can
33+
> handle fluctuating passenger traffic throughout the day with consistent staffing, optimizing both
34+
> resource utilization and passenger throughput.
35+
36+
### In plain words
37+
38+
> Thread-Pool Executor keeps a set of reusable threads that process multiple tasks throughout their
39+
> lifecycle, rather than creating a new thread for each task.
40+
41+
### Wikipedia says
42+
43+
> A thread pool is a software design pattern for achieving concurrency of execution in a computer
44+
> program. Often also called a replicated workers or worker-crew model, a thread pool maintains
45+
> multiple threads waiting for tasks to be allocated for concurrent execution by the supervising
46+
> program.
47+
48+
### Class diagram
49+
50+
![Thread-pool-executor Class diagram](./etc/thread-pool-executor.urm.png)
51+
52+
## Programmatic Example of Thread-Pool Executor Pattern in Java
53+
54+
Imagine a hotel front desk.
55+
56+
The number of employees (thread pool) is limited, but guests (tasks) keep arriving endlessly.
57+
58+
The Thread-Pool Executor pattern efficiently handles a large number of requests by reusing a small
59+
set of threads.
60+
61+
```java
62+
@Slf4j
63+
public class HotelFrontDesk {
64+
public static void main(String[] args) throws InterruptedException, ExecutionException {
65+
// Hire 3 front desk employees (threads)
66+
ExecutorService frontDesk = Executors.newFixedThreadPool(3);
67+
68+
LOGGER.info("Hotel front desk operation started!");
69+
70+
// 7 regular guests checking in (Runnable)
71+
for (int i = 1; i <= 7; i++) {
72+
String guestName = "Guest-" + i;
73+
frontDesk.submit(() -> {
74+
String employeeName = Thread.currentThread().getName();
75+
LOGGER.info("{} is checking in {}...", employeeName, guestName);
76+
try {
77+
Thread.sleep(2000); // Simulate check-in time
78+
} catch (InterruptedException e) {
79+
Thread.currentThread().interrupt();
80+
}
81+
LOGGER.info("{} has been successfully checked in!", guestName);
82+
});
83+
}
84+
85+
// 3 VIP guests checking in (Callable with result)
86+
Callable<String> vipGuest1 = createVipGuest("VIP-Guest-1");
87+
Callable<String> vipGuest2 = createVipGuest("VIP-Guest-2");
88+
Callable<String> vipGuest3 = createVipGuest("VIP-Guest-3");
89+
90+
Future<String> vipResult1 = frontDesk.submit(vipGuest1);
91+
Future<String> vipResult2 = frontDesk.submit(vipGuest2);
92+
Future<String> vipResult3 = frontDesk.submit(vipGuest3);
93+
94+
// Shutdown after submitting all tasks
95+
frontDesk.shutdown();
96+
97+
if (frontDesk.awaitTermination(1, TimeUnit.HOURS)) {
98+
// Print VIP guests' check-in results
99+
LOGGER.info("VIP Check-in Results:");
100+
LOGGER.info(vipResult1.get());
101+
LOGGER.info(vipResult2.get());
102+
LOGGER.info(vipResult3.get());
103+
LOGGER.info("All guests have been successfully checked in. Front desk is now closed.");
104+
} else {
105+
LOGGER.info("Check-in timeout. Forcefully shutting down the front desk.");
106+
}
107+
}
108+
109+
private static Callable<String> createVipGuest(String vipGuestName) {
110+
return () -> {
111+
String employeeName = Thread.currentThread().getName();
112+
LOGGER.info("{} is checking in VIP guest {}...", employeeName, vipGuestName);
113+
Thread.sleep(1000); // VIPs are faster to check in
114+
return vipGuestName + " has been successfully checked in!";
115+
};
116+
}
117+
}
118+
```
119+
120+
Here's the console output:
121+
122+
```markdown
123+
Hotel front desk operation started!
124+
pool-1-thread-3 is checking in Guest-3...
125+
pool-1-thread-2 is checking in Guest-2...
126+
pool-1-thread-1 is checking in Guest-1...
127+
Guest-2 has been successfully checked in!
128+
Guest-1 has been successfully checked in!
129+
Guest-3 has been successfully checked in!
130+
pool-1-thread-2 is checking in Guest-5...
131+
pool-1-thread-3 is checking in Guest-4...
132+
pool-1-thread-1 is checking in Guest-6...
133+
Guest-5 has been successfully checked in!
134+
pool-1-thread-2 is checking in Guest-7...
135+
Guest-4 has been successfully checked in!
136+
pool-1-thread-3 is checking in VIP guest VIP-Guest-1...
137+
Guest-6 has been successfully checked in!
138+
pool-1-thread-1 is checking in VIP guest VIP-Guest-2...
139+
pool-1-thread-3 is checking in VIP guest VIP-Guest-3...
140+
Guest-7 has been successfully checked in!
141+
VIP Check-in Results:
142+
VIP-Guest-1 has been successfully checked in!
143+
VIP-Guest-2 has been successfully checked in!
144+
VIP-Guest-3 has been successfully checked in!
145+
All guests have been successfully checked in. Front desk is now closed.
146+
```
147+
148+
**Note:** Since this example demonstrates asynchronous thread execution, **the actual output may vary between runs**. The order of execution and timing can differ due to thread scheduling, system load, and other factors that affect concurrent processing. The core behavior of the thread pool (limiting concurrent tasks to the number of threads and reusing threads) will remain consistent, but the exact sequence of log messages may change with each execution.
149+
150+
## When to Use the Thread-Pool Executor Pattern in Java
151+
152+
* When you need to limit the number of threads running simultaneously to avoid resource exhaustion
153+
* For applications that process a large number of short-lived independent tasks
154+
* To improve performance by reducing thread creation/destruction overhead
155+
* When implementing server applications that handle multiple client requests concurrently
156+
* To execute recurring tasks at fixed rates or with fixed delays
157+
158+
## Thread-Pool Executor Pattern Java Tutorial
159+
160+
* [Thread-Pool Executor Pattern Tutorial (Baeldung)](https://www.baeldung.com/thread-pool-java-and-guava)
161+
162+
## Real-World Applications of Thread-Pool Executor Pattern in Java
163+
164+
* Application servers like Tomcat and Jetty use thread pools to handle HTTP requests
165+
* Database connection pools in JDBC implementations
166+
* Background job processing frameworks like Spring Batch
167+
* Task scheduling systems like Quartz Scheduler
168+
* Java EE's Managed Executor Service for enterprise applications
169+
170+
## Benefits and Trade-offs of Thread-Pool Executor Pattern
171+
172+
### Benefits
173+
174+
* Improves performance by reusing existing threads instead of creating new ones
175+
* Provides better resource management by limiting the number of active threads
176+
* Simplifies thread lifecycle management and cleanup
177+
* Facilitates easy implementation of task prioritization and scheduling
178+
* Enhances application stability by preventing resource exhaustion
179+
180+
### Trade-offs
181+
182+
* May lead to thread starvation if improperly configured (too few threads)
183+
* Potential for resource underutilization if improperly sized (too many threads)
184+
* Requires careful shutdown handling to prevent task loss or resource leaks
185+
186+
## Related Java Design Patterns
187+
188+
* [Master-Worker Pattern](https://java-design-patterns.com/patterns/master-worker/): Tasks between a
189+
master and multiple workers.
190+
* [Producer-Consumer Pattern](https://java-design-patterns.com/patterns/producer-consumer/):
191+
Separates task production and task consumption, typically using a blocking queue.
192+
* [Object Pool Pattern](https://java-design-patterns.com/patterns/object-pool/): Reuses a set of
193+
objects (e.g., threads) instead of creating/destroying them repeatedly.
194+
195+
## References and Credits
196+
197+
* [Java Documentation for ThreadPoolExecutor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html)
198+
* [Java Concurrency in Practice](https://jcip.net/) by Brian Goetz
199+
* [Effective Java](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/) by Joshua
200+
Bloch

‎thread-pool-executor/etc/thread-pool-executor.urm.png

84.1 KB
Loading

‎thread-pool-executor/etc/thread-pool-executor.urm.puml

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
@startuml
2+
3+
interface Runnable {
4+
+run(): void
5+
}
6+
7+
interface Callable<T> {
8+
+call(): T
9+
}
10+
11+
interface ExecutorService {
12+
+submit(task: Runnable): Future<?>
13+
+submit(task: Callable<T>): Future<T>
14+
+shutdown(): void
15+
+awaitTermination(timeout: long, unit: TimeUnit): boolean
16+
}
17+
18+
class ThreadPoolExecutor {
19+
-corePoolSize: int
20+
-maximumPoolSize: int
21+
-keepAliveTime: long
22+
-workQueue: BlockingQueue<Runnable>
23+
+execute(task: Runnable): void
24+
+submit(task: Callable<T>): Future<T>
25+
}
26+
27+
class ThreadPoolManager {
28+
-executorService: ExecutorService
29+
+ThreadPoolManager(numThreads: int)
30+
+submitTask(task: Runnable): void
31+
+submitCallable(task: Callable<T>): Future<T>
32+
+shutdown(): void
33+
+awaitTermination(timeout: long, unit: TimeUnit): boolean
34+
}
35+
36+
class Task {
37+
-id: int
38+
-name: String
39+
-processingTime: long
40+
+Task(id: int, name: String, processingTime: long)
41+
+run(): void
42+
+call(): TaskResult
43+
}
44+
45+
class TaskResult {
46+
-taskId: int
47+
-taskName: String
48+
-executionTime: long
49+
+TaskResult(taskId: int, taskName: String, executionTime: long)
50+
}
51+
52+
class App {
53+
+main(args: String[]): void
54+
-executeRunnableTasks(poolManager: ThreadPoolManager): void
55+
-executeCallableTasks(poolManager: ThreadPoolManager): void
56+
}
57+
58+
ExecutorService <|-- ThreadPoolExecutor : implements
59+
Task ..|> Runnable : implements
60+
Task ..|> Callable : implements
61+
Task --> TaskResult : produces
62+
ThreadPoolManager --> ExecutorService : wraps
63+
App --> ThreadPoolManager : uses
64+
App --> Task : creates
65+
66+
@enduml

‎thread-pool-executor/pom.xml

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
4+
This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
5+
6+
The MIT License
7+
Copyright © 2014-2022 Ilkka Seppälä
8+
9+
Permission is hereby granted, free of charge, to any person obtaining a copy
10+
of this software and associated documentation files (the "Software"), to deal
11+
in the Software without restriction, including without limitation the rights
12+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13+
copies of the Software, and to permit persons to whom the Software is
14+
furnished to do so, subject to the following conditions:
15+
16+
The above copyright notice and this permission notice shall be included in
17+
all copies or substantial portions of the Software.
18+
19+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25+
THE SOFTWARE.
26+
27+
-->
28+
<project xmlns="http://maven.apache.org/POM/4.0.0"
29+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
30+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
31+
http://maven.apache.org/xsd/maven-4.0.0.xsd">
32+
33+
<modelVersion>4.0.0</modelVersion>
34+
35+
<parent>
36+
<groupId>com.iluwatar</groupId>
37+
<artifactId>java-design-patterns</artifactId>
38+
<version>1.26.0-SNAPSHOT</version>
39+
</parent>
40+
41+
<artifactId>thread-pool-executor</artifactId>
42+
43+
<dependencies>
44+
<dependency>
45+
<groupId>org.slf4j</groupId>
46+
<artifactId>slf4j-api</artifactId>
47+
</dependency>
48+
<dependency>
49+
<groupId>ch.qos.logback</groupId>
50+
<artifactId>logback-classic</artifactId>
51+
</dependency>
52+
<dependency>
53+
<groupId>org.junit.jupiter</groupId>
54+
<artifactId>junit-jupiter-engine</artifactId>
55+
<scope>test</scope>
56+
</dependency>
57+
<dependency>
58+
<groupId>org.mockito</groupId>
59+
<artifactId>mockito-core</artifactId>
60+
<scope>test</scope>
61+
</dependency>
62+
</dependencies>
63+
64+
<build>
65+
<plugins>
66+
<plugin>
67+
<groupId>org.apache.maven.plugins</groupId>
68+
<artifactId>maven-assembly-plugin</artifactId>
69+
<executions>
70+
<execution>
71+
<configuration>
72+
<archive>
73+
<manifest>
74+
<mainClass>com.iluwatar.threadpoolexecutor.App</mainClass>
75+
</manifest>
76+
</archive>
77+
</configuration>
78+
</execution>
79+
</executions>
80+
</plugin>
81+
</plugins>
82+
</build>
83+
</project>

0 commit comments

Comments
 (0)