From 8529017e025e4b0c8887730b5204926ef410f629 Mon Sep 17 00:00:00 2001 From: yoobin_mion <113106136+yybmion@users.noreply.github.com> Date: Fri, 16 May 2025 03:53:37 +0900 Subject: [PATCH] feat: Implement Thread-Pool Executor pattern (#3271) - 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 #3226 --- pom.xml | 1 + thread-pool-executor/README.md | 200 ++++++++++++++ .../etc/thread-pool-executor.urm.png | Bin 0 -> 86163 bytes .../etc/thread-pool-executor.urm.puml | 66 +++++ thread-pool-executor/pom.xml | 83 ++++++ .../com/iluwatar/threadpoolexecutor/App.java | 90 +++++++ .../threadpoolexecutor/FrontDeskService.java | 108 ++++++++ .../threadpoolexecutor/GuestCheckInTask.java | 52 ++++ .../VipGuestCheckInTask.java | 52 ++++ .../iluwatar/threadpoolexecutor/AppTest.java | 38 +++ .../FrontDeskServiceTest.java | 248 ++++++++++++++++++ .../GuestCheckInTaskTest.java | 55 ++++ .../VipGuestCheckInTaskTest.java | 48 ++++ 13 files changed, 1041 insertions(+) create mode 100644 thread-pool-executor/README.md create mode 100644 thread-pool-executor/etc/thread-pool-executor.urm.png create mode 100644 thread-pool-executor/etc/thread-pool-executor.urm.puml create mode 100644 thread-pool-executor/pom.xml create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java diff --git a/pom.xml b/pom.xml index d9667ed35..8337c9796 100644 --- a/pom.xml +++ b/pom.xml @@ -231,6 +231,7 @@ table-module template-method templateview + thread-pool-executor throttling tolerant-reader trampoline diff --git a/thread-pool-executor/README.md b/thread-pool-executor/README.md new file mode 100644 index 000000000..fa1d5a2c8 --- /dev/null +++ b/thread-pool-executor/README.md @@ -0,0 +1,200 @@ +--- +title: "Thread-Pool Executor Pattern in Java: Efficient Concurrent Task Management" +shortTitle: Thread-Pool Executor +description: "Learn the Thread-Pool Executor pattern in Java with practical examples, class +diagrams, and implementation details. Understand how to manage concurrent tasks efficiently, +improving resource utilization and application performance." +category: Concurrency +language: en +tag: + +- Performance +- Resource Management +- Concurrency +- Multithreading +- Scalability + +--- + +## Intent of Thread-Pool Executor Design Pattern + +The Thread-Pool Executor pattern maintains a pool of worker threads to execute tasks concurrently, +optimizing resource usage by reusing existing threads instead of creating new ones for each task. + +## Detailed Explanation of Thread-Pool Executor Pattern with Real-World Examples + +### Real-world example + +> Imagine a busy airport security checkpoint where instead of opening a new lane for each traveler, +> a fixed number of security lanes (threads) are open to process all passengers. Each security +> officer (thread) processes one passenger (task) at a time, and when finished, immediately calls the +> next passenger in line. During peak travel times, passengers wait in a queue, but the system is much +> more efficient than trying to open a new security lane for each individual traveler. The airport can +> handle fluctuating passenger traffic throughout the day with consistent staffing, optimizing both +> resource utilization and passenger throughput. + +### In plain words + +> Thread-Pool Executor keeps a set of reusable threads that process multiple tasks throughout their +> lifecycle, rather than creating a new thread for each task. + +### Wikipedia says + +> A thread pool is a software design pattern for achieving concurrency of execution in a computer +> program. Often also called a replicated workers or worker-crew model, a thread pool maintains +> multiple threads waiting for tasks to be allocated for concurrent execution by the supervising +> program. + +### Class diagram + +![Thread-pool-executor Class diagram](./etc/thread-pool-executor.urm.png) + +## Programmatic Example of Thread-Pool Executor Pattern in Java + +Imagine a hotel front desk. + +The number of employees (thread pool) is limited, but guests (tasks) keep arriving endlessly. + +The Thread-Pool Executor pattern efficiently handles a large number of requests by reusing a small +set of threads. + +```java +@Slf4j +public class HotelFrontDesk { + public static void main(String[] args) throws InterruptedException, ExecutionException { + // Hire 3 front desk employees (threads) + ExecutorService frontDesk = Executors.newFixedThreadPool(3); + + LOGGER.info("Hotel front desk operation started!"); + + // 7 regular guests checking in (Runnable) + for (int i = 1; i <= 7; i++) { + String guestName = "Guest-" + i; + frontDesk.submit(() -> { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in {}...", employeeName, guestName); + try { + Thread.sleep(2000); // Simulate check-in time + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + LOGGER.info("{} has been successfully checked in!", guestName); + }); + } + + // 3 VIP guests checking in (Callable with result) + Callable vipGuest1 = createVipGuest("VIP-Guest-1"); + Callable vipGuest2 = createVipGuest("VIP-Guest-2"); + Callable vipGuest3 = createVipGuest("VIP-Guest-3"); + + Future vipResult1 = frontDesk.submit(vipGuest1); + Future vipResult2 = frontDesk.submit(vipGuest2); + Future vipResult3 = frontDesk.submit(vipGuest3); + + // Shutdown after submitting all tasks + frontDesk.shutdown(); + + if (frontDesk.awaitTermination(1, TimeUnit.HOURS)) { + // Print VIP guests' check-in results + LOGGER.info("VIP Check-in Results:"); + LOGGER.info(vipResult1.get()); + LOGGER.info(vipResult2.get()); + LOGGER.info(vipResult3.get()); + LOGGER.info("All guests have been successfully checked in. Front desk is now closed."); + } else { + LOGGER.info("Check-in timeout. Forcefully shutting down the front desk."); + } + } + + private static Callable createVipGuest(String vipGuestName) { + return () -> { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in VIP guest {}...", employeeName, vipGuestName); + Thread.sleep(1000); // VIPs are faster to check in + return vipGuestName + " has been successfully checked in!"; + }; + } +} +``` + +Here's the console output: + +```markdown +Hotel front desk operation started! +pool-1-thread-3 is checking in Guest-3... +pool-1-thread-2 is checking in Guest-2... +pool-1-thread-1 is checking in Guest-1... +Guest-2 has been successfully checked in! +Guest-1 has been successfully checked in! +Guest-3 has been successfully checked in! +pool-1-thread-2 is checking in Guest-5... +pool-1-thread-3 is checking in Guest-4... +pool-1-thread-1 is checking in Guest-6... +Guest-5 has been successfully checked in! +pool-1-thread-2 is checking in Guest-7... +Guest-4 has been successfully checked in! +pool-1-thread-3 is checking in VIP guest VIP-Guest-1... +Guest-6 has been successfully checked in! +pool-1-thread-1 is checking in VIP guest VIP-Guest-2... +pool-1-thread-3 is checking in VIP guest VIP-Guest-3... +Guest-7 has been successfully checked in! +VIP Check-in Results: +VIP-Guest-1 has been successfully checked in! +VIP-Guest-2 has been successfully checked in! +VIP-Guest-3 has been successfully checked in! +All guests have been successfully checked in. Front desk is now closed. +``` + +**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. + +## When to Use the Thread-Pool Executor Pattern in Java + +* When you need to limit the number of threads running simultaneously to avoid resource exhaustion +* For applications that process a large number of short-lived independent tasks +* To improve performance by reducing thread creation/destruction overhead +* When implementing server applications that handle multiple client requests concurrently +* To execute recurring tasks at fixed rates or with fixed delays + +## Thread-Pool Executor Pattern Java Tutorial + +* [Thread-Pool Executor Pattern Tutorial (Baeldung)](https://www.baeldung.com/thread-pool-java-and-guava) + +## Real-World Applications of Thread-Pool Executor Pattern in Java + +* Application servers like Tomcat and Jetty use thread pools to handle HTTP requests +* Database connection pools in JDBC implementations +* Background job processing frameworks like Spring Batch +* Task scheduling systems like Quartz Scheduler +* Java EE's Managed Executor Service for enterprise applications + +## Benefits and Trade-offs of Thread-Pool Executor Pattern + +### Benefits + +* Improves performance by reusing existing threads instead of creating new ones +* Provides better resource management by limiting the number of active threads +* Simplifies thread lifecycle management and cleanup +* Facilitates easy implementation of task prioritization and scheduling +* Enhances application stability by preventing resource exhaustion + +### Trade-offs + +* May lead to thread starvation if improperly configured (too few threads) +* Potential for resource underutilization if improperly sized (too many threads) +* Requires careful shutdown handling to prevent task loss or resource leaks + +## Related Java Design Patterns + +* [Master-Worker Pattern](https://java-design-patterns.com/patterns/master-worker/): Tasks between a + master and multiple workers. +* [Producer-Consumer Pattern](https://java-design-patterns.com/patterns/producer-consumer/): + Separates task production and task consumption, typically using a blocking queue. +* [Object Pool Pattern](https://java-design-patterns.com/patterns/object-pool/): Reuses a set of + objects (e.g., threads) instead of creating/destroying them repeatedly. + +## References and Credits + +* [Java Documentation for ThreadPoolExecutor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html) +* [Java Concurrency in Practice](https://jcip.net/) by Brian Goetz +* [Effective Java](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/) by Joshua + Bloch diff --git a/thread-pool-executor/etc/thread-pool-executor.urm.png b/thread-pool-executor/etc/thread-pool-executor.urm.png new file mode 100644 index 0000000000000000000000000000000000000000..d426343f81712c249e609e27f433194a9b339479 GIT binary patch literal 86163 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%0AN&-T#}*(_KYE5EIwfo} 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 L=3J)G1=s%z2PWA^ literal 0 HcmV?d00001 diff --git a/thread-pool-executor/etc/thread-pool-executor.urm.puml b/thread-pool-executor/etc/thread-pool-executor.urm.puml new file mode 100644 index 000000000..ca83f40c1 --- /dev/null +++ b/thread-pool-executor/etc/thread-pool-executor.urm.puml @@ -0,0 +1,66 @@ +@startuml + +interface Runnable { + +run(): void +} + +interface Callable { + +call(): T +} + +interface ExecutorService { + +submit(task: Runnable): Future + +submit(task: Callable): Future + +shutdown(): void + +awaitTermination(timeout: long, unit: TimeUnit): boolean +} + +class ThreadPoolExecutor { + -corePoolSize: int + -maximumPoolSize: int + -keepAliveTime: long + -workQueue: BlockingQueue + +execute(task: Runnable): void + +submit(task: Callable): Future +} + +class ThreadPoolManager { + -executorService: ExecutorService + +ThreadPoolManager(numThreads: int) + +submitTask(task: Runnable): void + +submitCallable(task: Callable): Future + +shutdown(): void + +awaitTermination(timeout: long, unit: TimeUnit): boolean +} + +class Task { + -id: int + -name: String + -processingTime: long + +Task(id: int, name: String, processingTime: long) + +run(): void + +call(): TaskResult +} + +class TaskResult { + -taskId: int + -taskName: String + -executionTime: long + +TaskResult(taskId: int, taskName: String, executionTime: long) +} + +class App { + +main(args: String[]): void + -executeRunnableTasks(poolManager: ThreadPoolManager): void + -executeCallableTasks(poolManager: ThreadPoolManager): void +} + +ExecutorService <|-- ThreadPoolExecutor : implements +Task ..|> Runnable : implements +Task ..|> Callable : implements +Task --> TaskResult : produces +ThreadPoolManager --> ExecutorService : wraps +App --> ThreadPoolManager : uses +App --> Task : creates + +@enduml \ No newline at end of file diff --git a/thread-pool-executor/pom.xml b/thread-pool-executor/pom.xml new file mode 100644 index 000000000..f77cd92c6 --- /dev/null +++ b/thread-pool-executor/pom.xml @@ -0,0 +1,83 @@ + + + + + 4.0.0 + + + com.iluwatar + java-design-patterns + 1.26.0-SNAPSHOT + + + thread-pool-executor + + + + org.slf4j + slf4j-api + + + ch.qos.logback + logback-classic + + + org.junit.jupiter + junit-jupiter-engine + test + + + org.mockito + mockito-core + test + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + + + + + + com.iluwatar.threadpoolexecutor.App + + + + + + + + + diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java new file mode 100644 index 000000000..0c1292b89 --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java @@ -0,0 +1,90 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import lombok.extern.slf4j.Slf4j; + +/** + * The Thread-Pool Executor pattern demonstrates how a pool of worker threads can be used to execute + * tasks concurrently. This pattern is particularly useful in scenarios where you need to execute a + * large number of independent tasks and want to limit the number of threads used. + * + *

In this example, a hotel front desk with a fixed number of employees processes guest + * check-ins. Each employee is represented by a thread, and each check-in is a task. + * + *

Key benefits demonstrated: + * + *

    + *
  • Resource management - Limiting the number of concurrent threads + *
  • Efficiency - Reusing threads instead of creating new ones for each task + *
  • Responsiveness - Handling many requests with limited resources + *
+ */ +@Slf4j +public class App { + + /** + * Program main entry point. + * + * @param args program runtime arguments + */ + public static void main(String[] args) throws InterruptedException, ExecutionException { + + FrontDeskService frontDesk = new FrontDeskService(5); + LOGGER.info("Hotel front desk operation started!"); + + LOGGER.info("Processing 30 regular guest check-ins..."); + for (int i = 1; i <= 30; i++) { + frontDesk.submitGuestCheckIn(new GuestCheckInTask("Guest-" + i)); + Thread.sleep(100); + } + + LOGGER.info("Processing 3 VIP guest check-ins..."); + List> vipResults = new ArrayList<>(); + + for (int i = 1; i <= 3; i++) { + Future result = + frontDesk.submitVipGuestCheckIn(new VipGuestCheckInTask("VIP-Guest-" + i)); + vipResults.add(result); + } + + frontDesk.shutdown(); + + if (frontDesk.awaitTermination(1, TimeUnit.HOURS)) { + LOGGER.info("VIP Check-in Results:"); + for (Future result : vipResults) { + LOGGER.info(result.get()); + } + LOGGER.info("All guests have been successfully checked in. Front desk is now closed."); + } else { + LOGGER.warn("Check-in timeout. Forcefully shutting down the front desk."); + } + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java new file mode 100644 index 000000000..b80236ee5 --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java @@ -0,0 +1,108 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import lombok.extern.slf4j.Slf4j; + +/** + * FrontDeskService represents the hotel's front desk with a fixed number of employees. This class + * demonstrates the Thread-Pool Executor pattern using Java's ExecutorService. + */ +@Slf4j +public class FrontDeskService { + + private final ExecutorService executorService; + private final int numberOfEmployees; + + /** + * Creates a new front desk with the specified number of employees. + * + * @param numberOfEmployees the number of employees (threads) at the front desk + */ + public FrontDeskService(int numberOfEmployees) { + this.numberOfEmployees = numberOfEmployees; + this.executorService = Executors.newFixedThreadPool(numberOfEmployees); + LOGGER.info("Front desk initialized with {} employees.", numberOfEmployees); + } + + /** + * Submits a regular guest check-in task to an available employee. + * + * @param task the check-in task to submit + * @return a Future representing pending completion of the task + */ + public Future submitGuestCheckIn(Runnable task) { + LOGGER.debug("Submitting regular guest check-in task"); + return executorService.submit(task, null); + } + + /** + * Submits a VIP guest check-in task to an available employee. + * + * @param task the VIP check-in task to submit + * @param the type of the task's result + * @return a Future representing pending completion of the task + */ + public Future submitVipGuestCheckIn(Callable task) { + LOGGER.debug("Submitting VIP guest check-in task"); + return executorService.submit(task); + } + + /** + * Closes the front desk after all currently checked-in guests are processed. No new check-ins + * will be accepted. + */ + public void shutdown() { + LOGGER.info("Front desk is closing - no new guests will be accepted."); + executorService.shutdown(); + } + + /** + * Waits for all check-in processes to complete or until timeout. + * + * @param timeout the maximum time to wait + * @param unit the time unit of the timeout argument + * @return true if all tasks completed, false if timeout elapsed + * @throws InterruptedException if interrupted while waiting + */ + public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException { + LOGGER.info("Waiting for all check-ins to complete (max wait: {} {})", timeout, unit); + return executorService.awaitTermination(timeout, unit); + } + + /** + * Gets the number of employees at the front desk. + * + * @return the number of employees + */ + public int getNumberOfEmployees() { + return numberOfEmployees; + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java new file mode 100644 index 000000000..d8a33fdfc --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java @@ -0,0 +1,52 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import lombok.AllArgsConstructor; +import lombok.extern.slf4j.Slf4j; + +/** + * GuestCheckInTask represents a regular guest check-in process. Implements Runnable because it + * performs an action without returning a result. + */ +@Slf4j +@AllArgsConstructor +public class GuestCheckInTask implements Runnable { + + private final String guestName; + + @Override + public void run() { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in {}...", employeeName, guestName); + try { + Thread.sleep(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + LOGGER.error("Check-in for {} was interrupted", guestName); + } + LOGGER.info("{} has been successfully checked in!", guestName); + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java new file mode 100644 index 000000000..3948c114f --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java @@ -0,0 +1,52 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.concurrent.Callable; +import lombok.AllArgsConstructor; +import lombok.extern.slf4j.Slf4j; + +/** + * VipGuestCheckInTask represents a VIP guest check-in process. Implements Callable because it + * returns a result (check-in confirmation). + */ +@Slf4j +@AllArgsConstructor +public class VipGuestCheckInTask implements Callable { + + private final String vipGuestName; + + @Override + public String call() throws Exception { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in VIP guest {}...", employeeName, vipGuestName); + + Thread.sleep(1000); + + String result = vipGuestName + " has been successfully checked in!"; + LOGGER.info("VIP check-in completed: {}", result); + return result; + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java new file mode 100644 index 000000000..13e3a5bee --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java @@ -0,0 +1,38 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ + +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; + +import org.junit.jupiter.api.Test; + +class AppTest { + + @Test + void appStartsWithoutException() { + assertDoesNotThrow(() -> App.main(new String[] {})); + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java new file mode 100644 index 000000000..8d0396bf0 --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java @@ -0,0 +1,248 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.Callable; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Future; +import java.util.concurrent.RejectedExecutionException; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Test; + +class FrontDeskServiceTest { + + /** + * Tests that the constructor correctly sets the number of employees (threads). This verifies the + * basic initialization of the thread pool. + */ + @Test + void testConstructorSetsCorrectNumberOfEmployees() { + int expectedEmployees = 3; + + FrontDeskService frontDesk = new FrontDeskService(expectedEmployees); + + assertEquals(expectedEmployees, frontDesk.getNumberOfEmployees()); + } + + /** + * Tests that the submitGuestCheckIn method returns a non-null Future object. This verifies the + * basic task submission functionality. + */ + @Test + void testSubmitGuestCheckInReturnsNonNullFuture() { + FrontDeskService frontDesk = new FrontDeskService(1); + + Runnable task = + () -> { + // Task that completes quickly + }; + + Future future = frontDesk.submitGuestCheckIn(task); + + assertNotNull(future); + } + + /** + * Tests that the submitVipGuestCheckIn method returns a non-null Future object. This verifies + * that tasks with return values can be submitted correctly. + */ + @Test + void testSubmitVipGuestCheckInReturnsNonNullFuture() { + FrontDeskService frontDesk = new FrontDeskService(1); + Callable task = () -> "VIP Check-in complete"; + + Future future = frontDesk.submitVipGuestCheckIn(task); + + assertNotNull(future); + } + + /** + * Tests that the shutdown and awaitTermination methods work correctly. This verifies the basic + * shutdown functionality of the thread pool. + */ + @Test + void testShutdownAndAwaitTermination() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + CountDownLatch taskLatch = new CountDownLatch(1); + + Runnable task = taskLatch::countDown; + + frontDesk.submitGuestCheckIn(task); + frontDesk.shutdown(); + boolean terminated = frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(terminated); + assertTrue(taskLatch.await(100, TimeUnit.MILLISECONDS)); + } + + /** + * Tests the thread pool's behavior under load with multiple tasks. This verifies that the thread + * pool limits concurrent execution to the number of threads, all submitted tasks are eventually + * completed, and threads are reused for multiple tasks. + */ + @Test + void testMultipleTasksUnderLoad() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + int taskCount = 10; + CountDownLatch tasksCompletedLatch = new CountDownLatch(taskCount); + AtomicInteger concurrentTasks = new AtomicInteger(0); + AtomicInteger maxConcurrentTasks = new AtomicInteger(0); + + for (int i = 0; i < taskCount; i++) { + frontDesk.submitGuestCheckIn( + () -> { + try { + int current = concurrentTasks.incrementAndGet(); + maxConcurrentTasks.updateAndGet(max -> Math.max(max, current)); + + Thread.sleep(100); + + concurrentTasks.decrementAndGet(); + tasksCompletedLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + } + + boolean allTasksCompleted = tasksCompletedLatch.await(2, TimeUnit.SECONDS); + + frontDesk.shutdown(); + frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allTasksCompleted); + assertEquals(2, maxConcurrentTasks.get()); + assertEquals(0, concurrentTasks.get()); + } + + /** + * Tests proper shutdown behavior under load. This verifies that after shutdown no new tasks are + * accepted, all previously submitted tasks are completed, and the executor terminates properly + * after all tasks complete. + */ + @Test + void testProperShutdownUnderLoad() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + int taskCount = 5; + CountDownLatch startedTasksLatch = new CountDownLatch(2); + CountDownLatch tasksCompletionLatch = new CountDownLatch(taskCount); + + for (int i = 0; i < taskCount; i++) { + frontDesk.submitGuestCheckIn( + () -> { + try { + startedTasksLatch.countDown(); + Thread.sleep(100); + tasksCompletionLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + } + + assertTrue(startedTasksLatch.await(1, TimeUnit.SECONDS)); + + frontDesk.shutdown(); + + assertThrows( + RejectedExecutionException.class, + () -> { + frontDesk.submitGuestCheckIn(() -> {}); + }); + + boolean allTasksCompleted = tasksCompletionLatch.await(2, TimeUnit.SECONDS); + + boolean terminated = frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allTasksCompleted); + assertTrue(terminated); + } + + /** + * Tests concurrent execution of different task types (regular and VIP). This verifies that both + * Runnable and Callable tasks can be processed concurrently, all tasks complete successfully, and + * Callable tasks return their results correctly. + */ + @Test + void testConcurrentRegularAndVipTasks() throws Exception { + FrontDeskService frontDesk = new FrontDeskService(3); + int regularTaskCount = 4; + int vipTaskCount = 3; + CountDownLatch allTasksLatch = new CountDownLatch(regularTaskCount + vipTaskCount); + + List> regularResults = new ArrayList<>(); + for (int i = 0; i < regularTaskCount; i++) { + Future result = + frontDesk.submitGuestCheckIn( + () -> { + try { + Thread.sleep(50); + allTasksLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + regularResults.add(result); + } + + List> vipResults = new ArrayList<>(); + for (int i = 0; i < vipTaskCount; i++) { + final int guestNum = i; + Future result = + frontDesk.submitVipGuestCheckIn( + () -> { + Thread.sleep(25); + allTasksLatch.countDown(); + return "VIP-" + guestNum + " checked in"; + }); + vipResults.add(result); + } + + boolean allCompleted = allTasksLatch.await(2, TimeUnit.SECONDS); + + frontDesk.shutdown(); + frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allCompleted); + + for (Future result : regularResults) { + assertTrue(result.isDone()); + } + + for (int i = 0; i < vipTaskCount; i++) { + Future result = vipResults.get(i); + assertTrue(result.isDone()); + assertEquals("VIP-" + i + " checked in", result.get()); + } + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java new file mode 100644 index 000000000..27bb75efd --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java @@ -0,0 +1,55 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.util.concurrent.atomic.AtomicReference; +import org.junit.jupiter.api.Test; + +class GuestCheckInTaskTest { + + /** + * Tests that the task executes in the current thread when called directly. This verifies that the + * thread name inside the task matches the calling thread. + */ + @Test + void testThreadNameInTask() { + String guestName = "TestGuest"; + AtomicReference capturedThreadName = new AtomicReference<>(); + + GuestCheckInTask task = + new GuestCheckInTask(guestName) { + @Override + public void run() { + capturedThreadName.set(Thread.currentThread().getName()); + } + }; + + task.run(); + + assertEquals(Thread.currentThread().getName(), capturedThreadName.get()); + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java new file mode 100644 index 000000000..d76d90625 --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java @@ -0,0 +1,48 @@ +/* + * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt). + * + * The MIT License + * Copyright © 2014-2022 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +import org.junit.jupiter.api.Test; + +class VipGuestCheckInTaskTest { + + /** + * Tests that the call method returns the expected result string. This verifies that the VIP + * check-in task correctly formats its result message. + */ + @Test + void testCallReturnsExpectedResult() throws Exception { + String vipGuestName = "TestVipGuest"; + VipGuestCheckInTask task = new VipGuestCheckInTask(vipGuestName); + + String result = task.call(); + + assertNotNull(result); + assertEquals("TestVipGuest has been successfully checked in!", result); + } +}