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