From 1c6994ad7093fcad3f4cb1c436f8a312daeb0997 Mon Sep 17 00:00:00 2001
From: Duo Zhang <zhangduo@apache.org>
Date: Mon, 17 May 2021 10:17:24 +0800
Subject: [PATCH] HBASE-25872 Add documentation for LoadBalancer about
 synchronization (#3267)

Signed-off-by: Xin Sun <ddupgs@gmail.com>
---
 .../hadoop/hbase/master/LoadBalancer.java       | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/LoadBalancer.java b/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/LoadBalancer.java
index adead284943..055be811bcb 100644
--- a/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/LoadBalancer.java
+++ b/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/LoadBalancer.java
@@ -42,6 +42,23 @@ import org.apache.yetus.audience.InterfaceAudience;
  * cluster.
  * <p/>
  * This class produces plans for the {@code AssignmentManager} to execute.
+ * <p/>
+ * About locking:
+ * <ul>
+ * <li>We will first call {@link #setClusterInfoProvider(ClusterInfoProvider)} and then
+ * {@link #initialize()} to initialize the balancer, and before calling {@link #initialize()}, we
+ * will never call any methods of this balancer. So these two methods do not need to be
+ * synchronized.</li>
+ * <li>The {@link #balanceCluster(Map)} method will use the {@link ClusterMetrics} which is set by
+ * {@link #updateClusterMetrics(ClusterMetrics)}, and also lots of configurations, which could be
+ * changed by {@link #onConfigurationChange(Configuration)}, so the easier way is to make these
+ * three methods synchronized. And since there will be only one balancing thread, this will not
+ * impact performance too much.</li>
+ * <li>The {@link #roundRobinAssignment(List, List)}, {@link #retainAssignment(Map, List)} and
+ * {@link #randomAssignment(RegionInfo, List)} could be called from multiple threads concurrently,
+ * so these three methods should not be synchronized, the implementation classes need to make sure
+ * that they are thread safe.</li>
+ * </ul>
  */
 @InterfaceAudience.Private
 public interface LoadBalancer extends Stoppable, ConfigurationObserver {