Fix the ClusterListener, ServerListener, ServerMonitorListener …

…API docs relevant to thread-safety (#1208) JAVA-5185
mongodb · Oct 4, 2023 · c7346ba · c7346ba
1 parent 92c90c6
commit c7346ba
Show file tree

Hide file tree

Showing 3 changed files with 8 additions and 5 deletions.
diff --git a/driver-core/src/main/com/mongodb/event/ClusterListener.java b/driver-core/src/main/com/mongodb/event/ClusterListener.java
@@ -21,10 +21,13 @@
 /**
  * A listener for cluster-related events.
  * <p>
- * 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, this guarantee does not mean that
+ * 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.
  * </p>
  * @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
@@ -21,7 +21,7 @@
 /**
  * A listener for server-related events
  * <p>
- * 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.
  * </p>
  * @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
@@ -23,7 +23,7 @@
 /**
  * A listener for server monitor-related events
  * <p>
- * 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.
  * </p>
  * @see ClusterListener
  * @see ServerListener