From 70692f647f44b92989a1d5d0b95db9822e34605e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?=
 <iluwatar@users.noreply.github.com>
Date: Sun, 20 Aug 2023 21:23:12 +0300
Subject: [PATCH] docs: readme improvements (#2572)

---
 monitor/README.md                             | 47 +++++++++++++++++--
 .../java/com/iluwatar/monitor/MainTest.java   |  2 +-
 2 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/monitor/README.md b/monitor/README.md
index 431c257805aa..25aa39f2229f 100644
--- a/monitor/README.md
+++ b/monitor/README.md
@@ -6,8 +6,15 @@ tag:
  - Performance
 ---
 
+## Also known as
+
+Monitor object pattern
+
 ## Intent
-Monitor pattern is used to create thread-safe objects and prevent conflicts between threads in concurrent applications.
+
+The primary intent is to provide a structured and controlled way for multiple threads or processes to safely access and 
+manipulate shared resources, such as variables, data structures, or critical sections of code, without causing conflicts 
+or race conditions.
 
 ## Explanation
 
@@ -61,8 +68,38 @@ getBalance always return total amount and the total amount should be same after
 ![alt text](./etc/monitor.urm.png "Monitor class diagram")
 
 ## Applicability
-Use the Monitor pattern when
 
-* we have a shared resource and there is critical section .
-* you want to create thread-safe objects .
-* you want to achieve mutual exclusion in high level programming language .
+The Monitor design pattern should be used in situations where you have shared resources that need to be accessed and 
+manipulated by multiple threads or processes concurrently. This pattern is particularly useful in scenarios where 
+synchronization is necessary to prevent race conditions, data corruption, and inconsistent states. Here are some 
+situations where you should consider using the Monitor pattern:
+
+1. **Shared Data**: When your application involves shared data structures, variables, or resources that need to be accessed and updated by multiple threads. Monitors ensure that only one thread can access the shared resource at a time, preventing conflicts and ensuring data consistency.
+
+2. **Critical Sections**: When you have critical sections of code that need to be executed by only one thread at a time. Critical sections are portions of code where shared resources are manipulated, and concurrent access could lead to problems. Monitors help ensure that only one thread can execute the critical section at any given time.
+
+3. **Thread Safety**: When you need to ensure thread safety without relying solely on low-level synchronization mechanisms like locks and semaphores. Monitors provide a higher-level abstraction that encapsulates synchronization and resource management.
+
+4. **Waiting and Signaling**: When you have scenarios where threads need to wait for certain conditions to be met before proceeding. Monitors often include mechanisms for threads to wait for specific conditions and for other threads to notify them when the conditions are satisfied.
+
+5. **Deadlock Prevention**: When you want to prevent deadlocks by providing a structured way to acquire and release locks on shared resources. Monitors help avoid common deadlock scenarios by ensuring that resource access is well-managed.
+
+6. **Concurrent Data Structures**: When you're implementing concurrent data structures, such as queues, stacks, or hash tables, where multiple threads need to manipulate the structure while maintaining its integrity.
+
+7. **Resource Sharing**: When multiple threads need to share limited resources, like connections to a database or access to a network socket. Monitors can help manage the allocation and release of these resources in a controlled manner.
+
+8. **Improved Maintainability**: When you want to encapsulate synchronization logic and shared resource management within a single object, improving code organization and making it easier to reason about concurrency-related code.
+
+However, it's important to note that the Monitor pattern might not be the best fit for all concurrency scenarios. In 
+some cases, other synchronization mechanisms like locks, semaphores, or concurrent data structures might be more 
+suitable. Additionally, modern programming languages and frameworks often provide higher-level concurrency constructs 
+that abstract away the complexities of low-level synchronization.
+
+Before applying the Monitor pattern, it's recommended to thoroughly analyze your application's concurrency requirements 
+and choose the synchronization approach that best suits your needs, taking into consideration factors like performance, 
+complexity, and available language features.
+
+## Related patterns
+
+* Active object
+* Double-checked locking
diff --git a/monitor/src/test/java/com/iluwatar/monitor/MainTest.java b/monitor/src/test/java/com/iluwatar/monitor/MainTest.java
index 4d1c217372d7..4d69aeebd5ef 100644
--- a/monitor/src/test/java/com/iluwatar/monitor/MainTest.java
+++ b/monitor/src/test/java/com/iluwatar/monitor/MainTest.java
@@ -37,7 +37,7 @@ void shouldExecuteApplicationWithoutException() {
   }
 
   @Test
-  void RunnerExecuteWithoutException() {
+  void runnerShouldExecuteWithoutException() {
     var bank = new Bank(4, 1000);
     var latch = new CountDownLatch(1);