From 08483a777844b78e31489a42903702a1cacb3927 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko
Date: Thu, 28 Sep 2023 17:14:50 -0600
Subject: [PATCH 1/5] Fix the `ClusterListener`, `ServerListener`,
`ServerMonitorListener` API docs relevant to thread-safety
JAVA-5185
---
.../src/main/com/mongodb/event/ClusterListener.java | 7 ++++---
driver-core/src/main/com/mongodb/event/ServerListener.java | 2 +-
.../src/main/com/mongodb/event/ServerMonitorListener.java | 2 +-
3 files changed, 6 insertions(+), 5 deletions(-)
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
index 68ca9df4755..31f968272fd 100644
--- a/driver-core/src/main/com/mongodb/event/ClusterListener.java
+++ b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -21,10 +21,11 @@
/**
* A listener for cluster-related events.
*
- * It does not have to be thread-safe. All events received by {@link ClusterListener}, {@link ServerListener},
+ * All events received by {@link ClusterListener}, {@link ServerListener},
* {@link ServerMonitorListener} are totally ordered (and the event order implies the happens-before order), provided that the listeners
- * are not shared by different {@code MongoClient}s. This means that even if you have a single class implementing all of
- * {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}, it does not have to be thread-safe.
+ * are not shared by different {@code MongoClient}s. This guarantee holds even if you have a single class implementing
+ * all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, if a listener writes to shared memory,
+ * the write actions still must be synchronized with read actions from that shared memory.
*
* @see ServerListener
* @see ServerMonitorListener
diff --git a/driver-core/src/main/com/mongodb/event/ServerListener.java b/driver-core/src/main/com/mongodb/event/ServerListener.java
index 2e68b8d66f0..ead6f4e1b51 100644
--- a/driver-core/src/main/com/mongodb/event/ServerListener.java
+++ b/driver-core/src/main/com/mongodb/event/ServerListener.java
@@ -21,7 +21,7 @@
/**
* A listener for server-related events
*
- * It does not have to be thread-safe, see {@link ClusterListener} for the details regarding the order of events.
+ * See {@link ClusterListener} for the details regarding the order of events and memory synchronization.
*
* @see ClusterListener
* @see ServerMonitorListener
diff --git a/driver-core/src/main/com/mongodb/event/ServerMonitorListener.java b/driver-core/src/main/com/mongodb/event/ServerMonitorListener.java
index 9708836ff4f..1c73ac30510 100644
--- a/driver-core/src/main/com/mongodb/event/ServerMonitorListener.java
+++ b/driver-core/src/main/com/mongodb/event/ServerMonitorListener.java
@@ -23,7 +23,7 @@
/**
* A listener for server monitor-related events
*
- * It does not have to be thread-safe, see {@link ClusterListener} for the details regarding the order of events.
+ * See {@link ClusterListener} for the details regarding the order of events and memory synchronization.
*
* @see ClusterListener
* @see ServerListener
From b035ce6bb97230851a1fd9df38b792e19e5a95f6 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko
Date: Thu, 28 Sep 2023 17:21:21 -0600
Subject: [PATCH 2/5] More clarifications
JAVA-5185
---
driver-core/src/main/com/mongodb/event/ClusterListener.java | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
index 31f968272fd..5f7760e6eeb 100644
--- a/driver-core/src/main/com/mongodb/event/ClusterListener.java
+++ b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -25,7 +25,8 @@
* {@link ServerMonitorListener} are totally ordered (and the event order implies the happens-before order), provided that the listeners
* are not shared by different {@code MongoClient}s. This guarantee holds even if you have a single class implementing
* all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, if a listener writes to shared memory,
- * the write actions still must be synchronized with read actions from that shared memory.
+ * the write actions still must be synchronized with read actions from that shared memory,
+ * if the read actions are done not as part of executing any of the listener methods by a @code MongoClient}.
*
* @see ServerListener
* @see ServerMonitorListener
From 2095467837ca2b9c12d9700a3914be661aa94f75 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko
Date: Thu, 28 Sep 2023 17:22:19 -0600
Subject: [PATCH 3/5] Fix a typo (missing `{`)
JAVA-5185
---
driver-core/src/main/com/mongodb/event/ClusterListener.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
index 5f7760e6eeb..6a37421077a 100644
--- a/driver-core/src/main/com/mongodb/event/ClusterListener.java
+++ b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -26,7 +26,7 @@
* are not shared by different {@code MongoClient}s. This guarantee holds even if you have a single class implementing
* all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, if a listener writes to shared memory,
* the write actions still must be synchronized with read actions from that shared memory,
- * if the read actions are done not as part of executing any of the listener methods by a @code MongoClient}.
+ * if the read actions are done not as part of executing any of the listener methods by a {@code MongoClient}.
*
* @see ServerListener
* @see ServerMonitorListener
From 41785186a98b2f4cabeb8780fb7f82c6da670c95 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko
Date: Tue, 3 Oct 2023 15:49:51 -0600
Subject: [PATCH 4/5] Emphasize that the specified scenario is not the only one
in which memory synchronization is needed
JAVA-5185
---
driver-core/src/main/com/mongodb/event/ClusterListener.java | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
index 6a37421077a..26825bd26cb 100644
--- a/driver-core/src/main/com/mongodb/event/ClusterListener.java
+++ b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -24,7 +24,8 @@
* All events received by {@link ClusterListener}, {@link ServerListener},
* {@link ServerMonitorListener} are totally ordered (and the event order implies the happens-before order), provided that the listeners
* are not shared by different {@code MongoClient}s. This guarantee holds even if you have a single class implementing
- * all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, if a listener writes to shared memory,
+ * all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, this guarantee does not mean that
+ * implementations automatically do not need to synchronize memory accesses. For example, if a listener writes to shared memory,
* the write actions still must be synchronized with read actions from that shared memory,
* if the read actions are done not as part of executing any of the listener methods by a {@code MongoClient}.
*
From 19f0da85a7b73b1bff806ed479a314f7789476d5 Mon Sep 17 00:00:00 2001
From: Valentin Kovalenko
Date: Wed, 4 Oct 2023 11:04:36 -0600
Subject: [PATCH 5/5] Address review concerns
JAVA-5185
---
driver-core/src/main/com/mongodb/event/ClusterListener.java | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
index 26825bd26cb..8524e06344c 100644
--- a/driver-core/src/main/com/mongodb/event/ClusterListener.java
+++ b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -25,9 +25,9 @@
* {@link ServerMonitorListener} are totally ordered (and the event order implies the happens-before order), provided that the listeners
* are not shared by different {@code MongoClient}s. This guarantee holds even if you have a single class implementing
* all of {@link ClusterListener}, {@link ServerListener}, {@link ServerMonitorListener}. However, this guarantee does not mean that
- * implementations automatically do not need to synchronize memory accesses. For example, if a listener writes to shared memory,
- * the write actions still must be synchronized with read actions from that shared memory,
- * if the read actions are done not as part of executing any of the listener methods by a {@code MongoClient}.
+ * implementations automatically do not need to synchronize memory accesses to prevent data races.
+ * For example, if data that the listener collects in memory is accessed outside of the normal execution of the listener
+ * by the {@code MongoClient}, then reading and writing actions must be synchronized.
*
* @see ServerListener
* @see ServerMonitorListener