grpc 1.46.3 → 1.53.1

data/src/core/ext/filters/client_channel/lb_policy/ring_hash/ring_hash.cc

@@ -16,84 +16,109 @@
 
 #include <grpc/support/port_platform.h>
 
+#include "src/core/ext/filters/client_channel/lb_policy/ring_hash/ring_hash.h"
+
+#include <inttypes.h>
 #include <stdlib.h>
-#include <string.h>
 
+#include <algorithm>
+#include <atomic>
+#include <cmath>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "absl/base/attributes.h"
+#include "absl/base/thread_annotations.h"
+#include "absl/container/inlined_vector.h"
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
 #include "absl/strings/numbers.h"
 #include "absl/strings/str_cat.h"
+#include "absl/strings/string_view.h"
+#include "absl/types/optional.h"
+
+#include <grpc/grpc.h>
+
 #define XXH_INLINE_ALL
 #include "xxhash.h"
 
-#include <grpc/support/alloc.h>
+#include <grpc/impl/connectivity_state.h>
+#include <grpc/support/log.h>
 
+#include "src/core/ext/filters/client_channel/client_channel.h"
 #include "src/core/ext/filters/client_channel/lb_policy/subchannel_list.h"
-#include "src/core/ext/filters/client_channel/lb_policy_registry.h"
-#include "src/core/ext/filters/client_channel/subchannel.h"
 #include "src/core/lib/address_utils/sockaddr_utils.h"
 #include "src/core/lib/channel/channel_args.h"
+#include "src/core/lib/config/core_configuration.h"
 #include "src/core/lib/debug/trace.h"
-#include "src/core/lib/gpr/string.h"
+#include "src/core/lib/gprpp/debug_location.h"
+#include "src/core/lib/gprpp/orphanable.h"
 #include "src/core/lib/gprpp/ref_counted_ptr.h"
 #include "src/core/lib/gprpp/sync.h"
+#include "src/core/lib/gprpp/unique_type_name.h"
+#include "src/core/lib/gprpp/work_serializer.h"
+#include "src/core/lib/iomgr/closure.h"
+#include "src/core/lib/iomgr/error.h"
+#include "src/core/lib/iomgr/exec_ctx.h"
+#include "src/core/lib/json/json.h"
+#include "src/core/lib/load_balancing/lb_policy.h"
+#include "src/core/lib/load_balancing/lb_policy_factory.h"
+#include "src/core/lib/load_balancing/subchannel_interface.h"
+#include "src/core/lib/resolver/server_address.h"
 #include "src/core/lib/transport/connectivity_state.h"
-#include "src/core/lib/transport/error_utils.h"
 
 namespace grpc_core {
 
-const char* kRequestRingHashAttribute = "request_ring_hash";
 TraceFlag grpc_lb_ring_hash_trace(false, "ring_hash_lb");
 
+UniqueTypeName RequestHashAttributeName() {
+  static UniqueTypeName::Factory kFactory("request_hash");
+  return kFactory.Create();
+}
+
 // Helper Parser method
-void ParseRingHashLbConfig(const Json& json, size_t* min_ring_size,
-                           size_t* max_ring_size,
-                           std::vector<grpc_error_handle>* error_list) {
-  *min_ring_size = 1024;
-  *max_ring_size = 8388608;
-  if (json.type() != Json::Type::OBJECT) {
-    error_list->push_back(GRPC_ERROR_CREATE_FROM_STATIC_STRING(
-        "ring_hash_experimental should be of type object"));
-    return;
-  }
-  const Json::Object& ring_hash = json.object_value();
-  auto ring_hash_it = ring_hash.find("min_ring_size");
-  if (ring_hash_it != ring_hash.end()) {
-    if (ring_hash_it->second.type() != Json::Type::NUMBER) {
-      error_list->push_back(GRPC_ERROR_CREATE_FROM_STATIC_STRING(
-          "field:min_ring_size error: should be of type number"));
-    } else {
-      *min_ring_size = gpr_parse_nonnegative_int(
-          ring_hash_it->second.string_value().c_str());
+
+const JsonLoaderInterface* RingHashConfig::JsonLoader(const JsonArgs&) {
+  static const auto* loader =
+      JsonObjectLoader<RingHashConfig>()
+          .OptionalField("minRingSize", &RingHashConfig::min_ring_size)
+          .OptionalField("maxRingSize", &RingHashConfig::max_ring_size)
+          .Finish();
+  return loader;
+}
+
+void RingHashConfig::JsonPostLoad(const Json&, const JsonArgs&,
+                                  ValidationErrors* errors) {
+  {
+    ValidationErrors::ScopedField field(errors, ".minRingSize");
+    if (!errors->FieldHasErrors() &&
+        (min_ring_size == 0 || min_ring_size > 8388608)) {
+      errors->AddError("must be in the range [1, 8388608]");
     }
   }
-  ring_hash_it = ring_hash.find("max_ring_size");
-  if (ring_hash_it != ring_hash.end()) {
-    if (ring_hash_it->second.type() != Json::Type::NUMBER) {
-      error_list->push_back(GRPC_ERROR_CREATE_FROM_STATIC_STRING(
-          "field:max_ring_size error: should be of type number"));
-    } else {
-      *max_ring_size = gpr_parse_nonnegative_int(
-          ring_hash_it->second.string_value().c_str());
+  {
+    ValidationErrors::ScopedField field(errors, ".maxRingSize");
+    if (!errors->FieldHasErrors() &&
+        (max_ring_size == 0 || max_ring_size > 8388608)) {
+      errors->AddError("must be in the range [1, 8388608]");
     }
   }
-  if (*min_ring_size == 0 || *min_ring_size > 8388608 || *max_ring_size == 0 ||
-      *max_ring_size > 8388608 || *min_ring_size > *max_ring_size) {
-    error_list->push_back(GRPC_ERROR_CREATE_FROM_STATIC_STRING(
-        "field:max_ring_size and or min_ring_size error: "
-        "values need to be in the range of 1 to 8388608 "
-        "and max_ring_size cannot be smaller than "
-        "min_ring_size"));
+  if (min_ring_size > max_ring_size) {
+    errors->AddError("max_ring_size cannot be smaller than min_ring_size");
   }
 }
 
 namespace {
 
-constexpr char kRingHash[] = "ring_hash_experimental";
+constexpr absl::string_view kRingHash = "ring_hash_experimental";
 
 class RingHashLbConfig : public LoadBalancingPolicy::Config {
  public:
   RingHashLbConfig(size_t min_ring_size, size_t max_ring_size)
       : min_ring_size_(min_ring_size), max_ring_size_(max_ring_size) {}
-  const char* name() const override { return kRingHash; }
+  absl::string_view name() const override { return kRingHash; }
   size_t min_ring_size() const { return min_ring_size_; }
   size_t max_ring_size() const { return max_ring_size_; }
 
@@ -106,21 +131,22 @@ class RingHashLbConfig : public LoadBalancingPolicy::Config {
 // ring_hash LB policy
 //
 
+constexpr size_t kRingSizeCapDefault = 4096;
+
 class RingHash : public LoadBalancingPolicy {
  public:
   explicit RingHash(Args args);
 
-  const char* name() const override { return kRingHash; }
+  absl::string_view name() const override { return kRingHash; }
 
-  void UpdateLocked(UpdateArgs args) override;
+  absl::Status UpdateLocked(UpdateArgs args) override;
   void ResetBackoffLocked() override;
 
  private:
   ~RingHash() override;
 
-  // Forward declarations.
+  // Forward declaration.
   class RingHashSubchannelList;
-  class Ring;
 
   // Data for a particular subchannel in a subchannel list.
   // This subclass adds the following functionality:
@@ -137,54 +163,56 @@ class RingHash : public LoadBalancingPolicy {
         : SubchannelData(subchannel_list, address, std::move(subchannel)),
           address_(address) {}
 
-    grpc_connectivity_state GetConnectivityState() const {
-      return connectivity_state_for_picker_.load(std::memory_order_relaxed);
-    }
-
     const ServerAddress& address() const { return address_; }
 
-    bool seen_failure_since_ready() const { return seen_failure_since_ready_; }
+    grpc_connectivity_state GetConnectivityState() const {
+      return connectivity_state_.load(std::memory_order_relaxed);
+    }
 
-    // Performs connectivity state updates that need to be done both when we
-    // first start watching and when a watcher notification is received.
-    void UpdateConnectivityStateLocked(
-        grpc_connectivity_state connectivity_state);
+    absl::Status GetConnectivityStatus() const {
+      MutexLock lock(&mu_);
+      return connectivity_status_;
+    }
 
    private:
     // Performs connectivity state updates that need to be done only
     // after we have started watching.
     void ProcessConnectivityChangeLocked(
-        grpc_connectivity_state connectivity_state) override;
+        absl::optional<grpc_connectivity_state> old_state,
+        grpc_connectivity_state new_state) override;
 
     ServerAddress address_;
-    grpc_connectivity_state last_connectivity_state_ = GRPC_CHANNEL_SHUTDOWN;
-    std::atomic<grpc_connectivity_state> connectivity_state_for_picker_{
-        GRPC_CHANNEL_IDLE};
-    bool seen_failure_since_ready_ = false;
+
+    // Last logical connectivity state seen.
+    // Note that this may differ from the state actually reported by the
+    // subchannel in some cases; for example, once this is set to
+    // TRANSIENT_FAILURE, we do not change it again until we get READY,
+    // so we skip any interim stops in CONNECTING.
+    // Uses an atomic so that it can be accessed outside of the WorkSerializer.
+    std::atomic<grpc_connectivity_state> connectivity_state_{GRPC_CHANNEL_IDLE};
+
+    mutable Mutex mu_;
+    absl::Status connectivity_status_ ABSL_GUARDED_BY(&mu_);
   };
 
-  // A list of subchannels.
+  // A list of subchannels and the ring containing those subchannels.
   class RingHashSubchannelList
       : public SubchannelList<RingHashSubchannelList, RingHashSubchannelData> {
    public:
-    RingHashSubchannelList(RingHash* policy, TraceFlag* tracer,
-                           ServerAddressList addresses,
-                           const grpc_channel_args& args)
-        : SubchannelList(policy, tracer, std::move(addresses),
-                         policy->channel_control_helper(), args) {
-      // Need to maintain a ref to the LB policy as long as we maintain
-      // any references to subchannels, since the subchannels'
-      // pollset_sets will include the LB policy's pollset_set.
-      policy->Ref(DEBUG_LOCATION, "subchannel_list").release();
-    }
+    struct RingEntry {
+      uint64_t hash;
+      RingHashSubchannelData* subchannel;
+    };
+
+    RingHashSubchannelList(RingHash* policy, ServerAddressList addresses,
+                           const ChannelArgs& args);
 
     ~RingHashSubchannelList() override {
       RingHash* p = static_cast<RingHash*>(policy());
       p->Unref(DEBUG_LOCATION, "subchannel_list");
     }
 
-    // Starts watching the subchannels in this list.
-    void StartWatchingLocked();
+    const std::vector<RingEntry>& ring() const { return ring_; }
 
     // Updates the counters of subchannels in each state when a
     // subchannel transitions from old_state to new_state.
@@ -193,87 +221,111 @@ class RingHash : public LoadBalancingPolicy {
 
     // Updates the RH policy's connectivity state based on the
     // subchannel list's state counters, creating new picker and new ring.
-    // Furthermore, return a bool indicating whether the aggregated state is
-    // Transient Failure.
-    bool UpdateRingHashConnectivityStateLocked();
-
-    // Create a new ring from this subchannel list.
-    RefCountedPtr<Ring> MakeRing();
+    // The index parameter indicates the index into the list of the subchannel
+    // whose status report triggered the call to
+    // UpdateRingHashConnectivityStateLocked().
+    // connection_attempt_complete is true if the subchannel just
+    // finished a connection attempt.
+    void UpdateRingHashConnectivityStateLocked(size_t index,
+                                               bool connection_attempt_complete,
+                                               absl::Status status);
 
    private:
-    size_t num_idle_ = 0;
+    size_t num_idle_;
     size_t num_ready_ = 0;
     size_t num_connecting_ = 0;
     size_t num_transient_failure_ = 0;
-  };
-
-  class Ring : public RefCounted<Ring> {
-   public:
-    struct Entry {
-      uint64_t hash;
-      RingHashSubchannelData* subchannel;
-    };
 
-    Ring(RingHash* parent,
-         RefCountedPtr<RingHashSubchannelList> subchannel_list);
+    std::vector<RingEntry> ring_;
 
-    const std::vector<Entry>& ring() const { return ring_; }
+    // The index of the subchannel currently doing an internally
+    // triggered connection attempt, if any.
+    absl::optional<size_t> internally_triggered_connection_index_;
 
-   private:
-    RefCountedPtr<RingHashSubchannelList> subchannel_list_;
-    std::vector<Entry> ring_;
+    // TODO(roth): If we ever change the helper UpdateState() API to not
+    // need the status reported for TRANSIENT_FAILURE state (because
+    // it's not currently actually used for anything outside of the picker),
+    // then we will no longer need this data member.
+    absl::Status last_failure_;
   };
 
   class Picker : public SubchannelPicker {
    public:
-    Picker(RefCountedPtr<RingHash> parent, RefCountedPtr<Ring> ring)
-        : parent_(std::move(parent)), ring_(std::move(ring)) {}
+    explicit Picker(RefCountedPtr<RingHashSubchannelList> subchannel_list)
+        : subchannel_list_(std::move(subchannel_list)) {}
+
+    ~Picker() override {
+      // Hop into WorkSerializer to unref the subchannel list, since that may
+      // trigger the unreffing of the underlying subchannels.
+      MakeOrphanable<WorkSerializerRunner>(std::move(subchannel_list_));
+    }
 
     PickResult Pick(PickArgs args) override;
 
    private:
-    // A fire-and-forget class that schedules subchannel connection attempts
-    // on the control plane WorkSerializer.
-    class SubchannelConnectionAttempter : public Orphanable {
+    // An interface for running a callback in the control plane WorkSerializer.
+    class WorkSerializerRunner : public Orphanable {
      public:
-      explicit SubchannelConnectionAttempter(
-          RefCountedPtr<RingHash> ring_hash_lb)
-          : ring_hash_lb_(std::move(ring_hash_lb)) {
+      explicit WorkSerializerRunner(
+          RefCountedPtr<RingHashSubchannelList> subchannel_list)
+          : subchannel_list_(std::move(subchannel_list)) {
         GRPC_CLOSURE_INIT(&closure_, RunInExecCtx, this, nullptr);
       }
 
-      void AddSubchannel(RefCountedPtr<SubchannelInterface> subchannel) {
-        subchannels_.push_back(std::move(subchannel));
-      }
-
       void Orphan() override {
         // Hop into ExecCtx, so that we're not holding the data plane mutex
         // while we run control-plane code.
-        ExecCtx::Run(DEBUG_LOCATION, &closure_, GRPC_ERROR_NONE);
+        ExecCtx::Run(DEBUG_LOCATION, &closure_, absl::OkStatus());
+      }
+
+      // Will be invoked inside of the WorkSerializer.
+      virtual void Run() {}
+
+     protected:
+      RingHash* ring_hash_lb() const {
+        return static_cast<RingHash*>(subchannel_list_->policy());
       }
 
      private:
       static void RunInExecCtx(void* arg, grpc_error_handle /*error*/) {
-        auto* self = static_cast<SubchannelConnectionAttempter*>(arg);
-        self->ring_hash_lb_->work_serializer()->Run(
+        auto* self = static_cast<WorkSerializerRunner*>(arg);
+        self->ring_hash_lb()->work_serializer()->Run(
             [self]() {
-              if (!self->ring_hash_lb_->shutdown_) {
-                for (auto& subchannel : self->subchannels_) {
-                  subchannel->AttemptToConnect();
-                }
-              }
+              self->Run();
               delete self;
             },
             DEBUG_LOCATION);
       }
 
-      RefCountedPtr<RingHash> ring_hash_lb_;
+      RefCountedPtr<RingHashSubchannelList> subchannel_list_;
       grpc_closure closure_;
-      absl::InlinedVector<RefCountedPtr<SubchannelInterface>, 10> subchannels_;
     };
 
-    RefCountedPtr<RingHash> parent_;
-    RefCountedPtr<Ring> ring_;
+    // A fire-and-forget class that schedules subchannel connection attempts
+    // on the control plane WorkSerializer.
+    class SubchannelConnectionAttempter : public WorkSerializerRunner {
+     public:
+      explicit SubchannelConnectionAttempter(
+          RefCountedPtr<RingHashSubchannelList> subchannel_list)
+          : WorkSerializerRunner(std::move(subchannel_list)) {}
+
+      void AddSubchannel(RefCountedPtr<SubchannelInterface> subchannel) {
+        subchannels_.push_back(std::move(subchannel));
+      }
+
+      void Run() override {
+        if (!ring_hash_lb()->shutdown_) {
+          for (auto& subchannel : subchannels_) {
+            subchannel->RequestConnection();
+          }
+        }
+      }
+
+     private:
+      std::vector<RefCountedPtr<SubchannelInterface>> subchannels_;
+    };
+
+    RefCountedPtr<RingHashSubchannelList> subchannel_list_;
   };
 
   void ShutdownLocked() override;
@@ -282,140 +334,35 @@ class RingHash : public LoadBalancingPolicy {
   RefCountedPtr<RingHashLbConfig> config_;
 
   // list of subchannels.
-  OrphanablePtr<RingHashSubchannelList> subchannel_list_;
+  RefCountedPtr<RingHashSubchannelList> subchannel_list_;
+  RefCountedPtr<RingHashSubchannelList> latest_pending_subchannel_list_;
   // indicating if we are shutting down.
   bool shutdown_ = false;
-
-  // Current ring.
-  RefCountedPtr<Ring> ring_;
 };
 
-//
-// RingHash::Ring
-//
-
-RingHash::Ring::Ring(RingHash* parent,
-                     RefCountedPtr<RingHashSubchannelList> subchannel_list)
-    : subchannel_list_(std::move(subchannel_list)) {
-  size_t num_subchannels = subchannel_list_->num_subchannels();
-  // Store the weights while finding the sum.
-  struct AddressWeight {
-    std::string address;
-    // Default weight is 1 for the cases where a weight is not provided,
-    // each occurrence of the address will be counted a weight value of 1.
-    uint32_t weight = 1;
-    double normalized_weight;
-  };
-  std::vector<AddressWeight> address_weights;
-  size_t sum = 0;
-  address_weights.reserve(num_subchannels);
-  for (size_t i = 0; i < num_subchannels; ++i) {
-    RingHashSubchannelData* sd = subchannel_list_->subchannel(i);
-    const ServerAddressWeightAttribute* weight_attribute = static_cast<
-        const ServerAddressWeightAttribute*>(sd->address().GetAttribute(
-        ServerAddressWeightAttribute::kServerAddressWeightAttributeKey));
-    AddressWeight address_weight;
-    address_weight.address =
-        grpc_sockaddr_to_string(&sd->address().address(), false);
-    if (weight_attribute != nullptr) {
-      GPR_ASSERT(weight_attribute->weight() != 0);
-      address_weight.weight = weight_attribute->weight();
-    }
-    sum += address_weight.weight;
-    address_weights.push_back(std::move(address_weight));
-  }
-  // Calculating normalized weights and find min and max.
-  double min_normalized_weight = 1.0;
-  double max_normalized_weight = 0.0;
-  for (auto& address : address_weights) {
-    address.normalized_weight = static_cast<double>(address.weight) / sum;
-    min_normalized_weight =
-        std::min(address.normalized_weight, min_normalized_weight);
-    max_normalized_weight =
-        std::max(address.normalized_weight, max_normalized_weight);
-  }
-  // Scale up the number of hashes per host such that the least-weighted host
-  // gets a whole number of hashes on the ring. Other hosts might not end up
-  // with whole numbers, and that's fine (the ring-building algorithm below can
-  // handle this). This preserves the original implementation's behavior: when
-  // weights aren't provided, all hosts should get an equal number of hashes. In
-  // the case where this number exceeds the max_ring_size, it's scaled back down
-  // to fit.
-  const size_t min_ring_size = parent->config_->min_ring_size();
-  const size_t max_ring_size = parent->config_->max_ring_size();
-  const double scale = std::min(
-      std::ceil(min_normalized_weight * min_ring_size) / min_normalized_weight,
-      static_cast<double>(max_ring_size));
-  // Reserve memory for the entire ring up front.
-  const uint64_t ring_size = std::ceil(scale);
-  ring_.reserve(ring_size);
-  // Populate the hash ring by walking through the (host, weight) pairs in
-  // normalized_host_weights, and generating (scale * weight) hashes for each
-  // host. Since these aren't necessarily whole numbers, we maintain running
-  // sums -- current_hashes and target_hashes -- which allows us to populate the
-  // ring in a mostly stable way.
-  absl::InlinedVector<char, 196> hash_key_buffer;
-  double current_hashes = 0.0;
-  double target_hashes = 0.0;
-  uint64_t min_hashes_per_host = ring_size;
-  uint64_t max_hashes_per_host = 0;
-  for (size_t i = 0; i < num_subchannels; ++i) {
-    const std::string& address_string = address_weights[i].address;
-    hash_key_buffer.assign(address_string.begin(), address_string.end());
-    hash_key_buffer.emplace_back('_');
-    auto offset_start = hash_key_buffer.end();
-    target_hashes += scale * address_weights[i].normalized_weight;
-    size_t count = 0;
-    while (current_hashes < target_hashes) {
-      const std::string count_str = absl::StrCat(count);
-      hash_key_buffer.insert(offset_start, count_str.begin(), count_str.end());
-      absl::string_view hash_key(hash_key_buffer.data(),
-                                 hash_key_buffer.size());
-      const uint64_t hash = XXH64(hash_key.data(), hash_key.size(), 0);
-      ring_.push_back({hash, subchannel_list_->subchannel(i)});
-      ++count;
-      ++current_hashes;
-      hash_key_buffer.erase(offset_start, hash_key_buffer.end());
-    }
-    min_hashes_per_host =
-        std::min(static_cast<uint64_t>(i), min_hashes_per_host);
-    max_hashes_per_host =
-        std::max(static_cast<uint64_t>(i), max_hashes_per_host);
-  }
-  std::sort(ring_.begin(), ring_.end(),
-            [](const Entry& lhs, const Entry& rhs) -> bool {
-              return lhs.hash < rhs.hash;
-            });
-  if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
-    gpr_log(GPR_INFO,
-            "[RH %p picker %p] created ring from subchannel_list=%p "
-            "with %" PRIuPTR " ring entries",
-            parent, this, subchannel_list_.get(), ring_.size());
-  }
-}
-
 //
 // RingHash::Picker
 //
 
 RingHash::PickResult RingHash::Picker::Pick(PickArgs args) {
-  auto hash =
-      args.call_state->ExperimentalGetCallAttribute(kRequestRingHashAttribute);
+  auto* call_state = static_cast<ClientChannel::LoadBalancedCall::LbCallState*>(
+      args.call_state);
+  auto hash = call_state->GetCallAttribute(RequestHashAttributeName());
   uint64_t h;
   if (!absl::SimpleAtoi(hash, &h)) {
     return PickResult::Fail(
-        absl::InternalError("xds ring hash value is not a number"));
+        absl::InternalError("ring hash value is not a number"));
   }
-  const std::vector<Ring::Entry>& ring = ring_->ring();
+  const auto& ring = subchannel_list_->ring();
   // Ported from https://github.com/RJ/ketama/blob/master/libketama/ketama.c
   // (ketama_get_server) NOTE: The algorithm depends on using signed integers
   // for lowp, highp, and first_index. Do not change them!
-  int64_t lowp = 0;
-  int64_t highp = ring.size();
-  int64_t first_index = 0;
+  size_t lowp = 0;
+  size_t highp = ring.size();
+  size_t first_index = 0;
   while (true) {
     first_index = (lowp + highp) / 2;
-    if (first_index == static_cast<int64_t>(ring.size())) {
+    if (first_index == ring.size()) {
       first_index = 0;
       break;
     }
@@ -439,7 +386,9 @@ RingHash::PickResult RingHash::Picker::Pick(PickArgs args) {
       [&](RefCountedPtr<SubchannelInterface> subchannel) {
         if (subchannel_connection_attempter == nullptr) {
           subchannel_connection_attempter =
-              MakeOrphanable<SubchannelConnectionAttempter>(parent_);
+              MakeOrphanable<SubchannelConnectionAttempter>(
+                  subchannel_list_->Ref(DEBUG_LOCATION,
+                                        "SubchannelConnectionAttempter"));
         }
         subchannel_connection_attempter->AddSubchannel(std::move(subchannel));
       };
@@ -464,7 +413,7 @@ RingHash::PickResult RingHash::Picker::Pick(PickArgs args) {
   bool found_second_subchannel = false;
   bool found_first_non_failed = false;
   for (size_t i = 1; i < ring.size(); ++i) {
-    const Ring::Entry& entry = ring[(first_index + i) % ring.size()];
+    const auto& entry = ring[(first_index + i) % ring.size()];
     if (entry.subchannel == ring[first_index].subchannel) {
       continue;
     }
@@ -499,35 +448,132 @@ RingHash::PickResult RingHash::Picker::Pick(PickArgs args) {
       }
     }
   }
-  return PickResult::Fail(absl::UnavailableError(
-      "xds ring hash found a subchannel that is in TRANSIENT_FAILURE state"));
+  return PickResult::Fail(absl::UnavailableError(absl::StrCat(
+      "ring hash cannot find a connected subchannel; first failure: ",
+      ring[first_index].subchannel->GetConnectivityStatus().ToString())));
 }
 
 //
 // RingHash::RingHashSubchannelList
 //
 
-void RingHash::RingHashSubchannelList::StartWatchingLocked() {
-  if (num_subchannels() == 0) return;
-  // Check current state of each subchannel synchronously.
+RingHash::RingHashSubchannelList::RingHashSubchannelList(
+    RingHash* policy, ServerAddressList addresses, const ChannelArgs& args)
+    : SubchannelList(policy,
+                     (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)
+                          ? "RingHashSubchannelList"
+                          : nullptr),
+                     std::move(addresses), policy->channel_control_helper(),
+                     args),
+      num_idle_(num_subchannels()) {
+  // Need to maintain a ref to the LB policy as long as we maintain
+  // any references to subchannels, since the subchannels'
+  // pollset_sets will include the LB policy's pollset_set.
+  policy->Ref(DEBUG_LOCATION, "subchannel_list").release();
+  // Construct the ring.
+  // Store the weights while finding the sum.
+  struct AddressWeight {
+    std::string address;
+    // Default weight is 1 for the cases where a weight is not provided,
+    // each occurrence of the address will be counted a weight value of 1.
+    uint32_t weight = 1;
+    double normalized_weight;
+  };
+  std::vector<AddressWeight> address_weights;
+  size_t sum = 0;
+  address_weights.reserve(num_subchannels());
   for (size_t i = 0; i < num_subchannels(); ++i) {
-    grpc_connectivity_state state =
-        subchannel(i)->CheckConnectivityStateLocked();
-    subchannel(i)->UpdateConnectivityStateLocked(state);
+    RingHashSubchannelData* sd = subchannel(i);
+    const ServerAddressWeightAttribute* weight_attribute = static_cast<
+        const ServerAddressWeightAttribute*>(sd->address().GetAttribute(
+        ServerAddressWeightAttribute::kServerAddressWeightAttributeKey));
+    AddressWeight address_weight;
+    address_weight.address =
+        grpc_sockaddr_to_string(&sd->address().address(), false).value();
+    // Weight should never be zero, but ignore it just in case, since
+    // that value would screw up the ring-building algorithm.
+    if (weight_attribute != nullptr && weight_attribute->weight() > 0) {
+      address_weight.weight = weight_attribute->weight();
+    }
+    sum += address_weight.weight;
+    address_weights.push_back(std::move(address_weight));
   }
-  // Start connectivity watch for each subchannel.
-  for (size_t i = 0; i < num_subchannels(); i++) {
-    if (subchannel(i)->subchannel() != nullptr) {
-      subchannel(i)->StartConnectivityWatchLocked();
+  // Calculating normalized weights and find min and max.
+  double min_normalized_weight = 1.0;
+  double max_normalized_weight = 0.0;
+  for (auto& address : address_weights) {
+    address.normalized_weight = static_cast<double>(address.weight) / sum;
+    min_normalized_weight =
+        std::min(address.normalized_weight, min_normalized_weight);
+    max_normalized_weight =
+        std::max(address.normalized_weight, max_normalized_weight);
+  }
+  // Scale up the number of hashes per host such that the least-weighted host
+  // gets a whole number of hashes on the ring. Other hosts might not end up
+  // with whole numbers, and that's fine (the ring-building algorithm below can
+  // handle this). This preserves the original implementation's behavior: when
+  // weights aren't provided, all hosts should get an equal number of hashes. In
+  // the case where this number exceeds the max_ring_size, it's scaled back down
+  // to fit.
+  const size_t ring_size_cap = args.GetInt(GRPC_ARG_RING_HASH_LB_RING_SIZE_CAP)
+                                   .value_or(kRingSizeCapDefault);
+  const size_t min_ring_size =
+      std::min(policy->config_->min_ring_size(), ring_size_cap);
+  const size_t max_ring_size =
+      std::min(policy->config_->max_ring_size(), ring_size_cap);
+  const double scale = std::min(
+      std::ceil(min_normalized_weight * min_ring_size) / min_normalized_weight,
+      static_cast<double>(max_ring_size));
+  // Reserve memory for the entire ring up front.
+  const size_t ring_size = std::ceil(scale);
+  ring_.reserve(ring_size);
+  // Populate the hash ring by walking through the (host, weight) pairs in
+  // normalized_host_weights, and generating (scale * weight) hashes for each
+  // host. Since these aren't necessarily whole numbers, we maintain running
+  // sums -- current_hashes and target_hashes -- which allows us to populate the
+  // ring in a mostly stable way.
+  absl::InlinedVector<char, 196> hash_key_buffer;
+  double current_hashes = 0.0;
+  double target_hashes = 0.0;
+  uint64_t min_hashes_per_host = ring_size;
+  uint64_t max_hashes_per_host = 0;
+  for (size_t i = 0; i < num_subchannels(); ++i) {
+    const std::string& address_string = address_weights[i].address;
+    hash_key_buffer.assign(address_string.begin(), address_string.end());
+    hash_key_buffer.emplace_back('_');
+    auto offset_start = hash_key_buffer.end();
+    target_hashes += scale * address_weights[i].normalized_weight;
+    size_t count = 0;
+    while (current_hashes < target_hashes) {
+      const std::string count_str = absl::StrCat(count);
+      hash_key_buffer.insert(offset_start, count_str.begin(), count_str.end());
+      absl::string_view hash_key(hash_key_buffer.data(),
+                                 hash_key_buffer.size());
+      const uint64_t hash = XXH64(hash_key.data(), hash_key.size(), 0);
+      ring_.push_back({hash, subchannel(i)});
+      ++count;
+      ++current_hashes;
+      hash_key_buffer.erase(offset_start, hash_key_buffer.end());
     }
+    min_hashes_per_host =
+        std::min(static_cast<uint64_t>(i), min_hashes_per_host);
+    max_hashes_per_host =
+        std::max(static_cast<uint64_t>(i), max_hashes_per_host);
+  }
+  std::sort(ring_.begin(), ring_.end(),
+            [](const RingHashSubchannelList::RingEntry& lhs,
+               const RingHashSubchannelList::RingEntry& rhs) -> bool {
+              return lhs.hash < rhs.hash;
+            });
+  if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
+    gpr_log(GPR_INFO,
+            "[RH %p] created subchannel list %p with %" PRIuPTR " ring entries",
+            policy, this, ring_.size());
   }
-  // Send updated state to parent based on reported subchannel states.
-  UpdateRingHashConnectivityStateLocked();
 }
 
 void RingHash::RingHashSubchannelList::UpdateStateCountersLocked(
     grpc_connectivity_state old_state, grpc_connectivity_state new_state) {
-  GPR_ASSERT(new_state != GRPC_CHANNEL_SHUTDOWN);
   if (old_state == GRPC_CHANNEL_IDLE) {
     GPR_ASSERT(num_idle_ > 0);
     --num_idle_;
@@ -541,6 +587,7 @@ void RingHash::RingHashSubchannelList::UpdateStateCountersLocked(
     GPR_ASSERT(num_transient_failure_ > 0);
     --num_transient_failure_;
   }
+  GPR_ASSERT(new_state != GRPC_CHANNEL_SHUTDOWN);
   if (new_state == GRPC_CHANNEL_IDLE) {
     ++num_idle_;
   } else if (new_state == GRPC_CHANNEL_READY) {
@@ -552,61 +599,115 @@ void RingHash::RingHashSubchannelList::UpdateStateCountersLocked(
   }
 }
 
-// Sets the RH policy's connectivity state and generates a new picker based
-// on the current subchannel list or requests an re-attempt by returning true..
-bool RingHash::RingHashSubchannelList::UpdateRingHashConnectivityStateLocked() {
+void RingHash::RingHashSubchannelList::UpdateRingHashConnectivityStateLocked(
+    size_t index, bool connection_attempt_complete, absl::Status status) {
   RingHash* p = static_cast<RingHash*>(policy());
+  // If this is latest_pending_subchannel_list_, then swap it into
+  // subchannel_list_ as soon as we get the initial connectivity state
+  // report for every subchannel in the list.
+  if (p->latest_pending_subchannel_list_.get() == this &&
+      AllSubchannelsSeenInitialState()) {
+    if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
+      gpr_log(GPR_INFO, "[RH %p] replacing subchannel list %p with %p", p,
+              p->subchannel_list_.get(), this);
+    }
+    p->subchannel_list_ = std::move(p->latest_pending_subchannel_list_);
+  }
   // Only set connectivity state if this is the current subchannel list.
-  if (p->subchannel_list_.get() != this) return false;
+  if (p->subchannel_list_.get() != this) return;
   // The overall aggregation rules here are:
   // 1. If there is at least one subchannel in READY state, report READY.
   // 2. If there are 2 or more subchannels in TRANSIENT_FAILURE state, report
-  // TRANSIENT_FAILURE.
+  //    TRANSIENT_FAILURE.
   // 3. If there is at least one subchannel in CONNECTING state, report
-  // CONNECTING.
-  // 4. If there is at least one subchannel in IDLE state, report IDLE.
-  // 5. Otherwise, report TRANSIENT_FAILURE.
+  //    CONNECTING.
+  // 4. If there is one subchannel in TRANSIENT_FAILURE state and there is
+  //    more than one subchannel, report CONNECTING.
+  // 5. If there is at least one subchannel in IDLE state, report IDLE.
+  // 6. Otherwise, report TRANSIENT_FAILURE.
+  //
+  // We set start_connection_attempt to true if we match rules 2, 3, or 6.
+  grpc_connectivity_state state;
+  bool start_connection_attempt = false;
   if (num_ready_ > 0) {
-    /* READY */
-    p->channel_control_helper()->UpdateState(
-        GRPC_CHANNEL_READY, absl::Status(),
-        absl::make_unique<Picker>(p->Ref(DEBUG_LOCATION, "RingHashPicker"),
-                                  p->ring_));
-    return false;
-  }
-  if (num_connecting_ > 0 && num_transient_failure_ < 2) {
-    p->channel_control_helper()->UpdateState(
-        GRPC_CHANNEL_CONNECTING, absl::Status(),
-        absl::make_unique<QueuePicker>(p->Ref(DEBUG_LOCATION, "QueuePicker")));
-    return false;
+    state = GRPC_CHANNEL_READY;
+  } else if (num_transient_failure_ >= 2) {
+    state = GRPC_CHANNEL_TRANSIENT_FAILURE;
+    start_connection_attempt = true;
+  } else if (num_connecting_ > 0) {
+    state = GRPC_CHANNEL_CONNECTING;
+  } else if (num_transient_failure_ == 1 && num_subchannels() > 1) {
+    state = GRPC_CHANNEL_CONNECTING;
+    start_connection_attempt = true;
+  } else if (num_idle_ > 0) {
+    state = GRPC_CHANNEL_IDLE;
+  } else {
+    state = GRPC_CHANNEL_TRANSIENT_FAILURE;
+    start_connection_attempt = true;
   }
-  if (num_idle_ > 0 && num_transient_failure_ < 2) {
-    p->channel_control_helper()->UpdateState(
-        GRPC_CHANNEL_IDLE, absl::Status(),
-        absl::make_unique<Picker>(p->Ref(DEBUG_LOCATION, "RingHashPicker"),
-                                  p->ring_));
-    return false;
+  // In TRANSIENT_FAILURE, report the last reported failure.
+  // Otherwise, report OK.
+  if (state == GRPC_CHANNEL_TRANSIENT_FAILURE) {
+    if (!status.ok()) {
+      last_failure_ = absl::UnavailableError(absl::StrCat(
+          "no reachable subchannels; last error: ", status.ToString()));
+    }
+    status = last_failure_;
+  } else {
+    status = absl::OkStatus();
   }
-  absl::Status status =
-      absl::UnavailableError("connections to backend failing or idle");
+  // Generate new picker and return it to the channel.
+  // Note that we use our own picker regardless of connectivity state.
   p->channel_control_helper()->UpdateState(
-      GRPC_CHANNEL_TRANSIENT_FAILURE, status,
-      absl::make_unique<TransientFailurePicker>(status));
-  return true;
-}
-
-RefCountedPtr<RingHash::Ring> RingHash::RingHashSubchannelList::MakeRing() {
-  RingHash* p = static_cast<RingHash*>(policy());
-  return MakeRefCounted<Ring>(p, Ref(DEBUG_LOCATION, "Ring"));
+      state, status,
+      MakeRefCounted<Picker>(Ref(DEBUG_LOCATION, "RingHashPicker")));
+  // While the ring_hash policy is reporting TRANSIENT_FAILURE, it will
+  // not be getting any pick requests from the priority policy.
+  // However, because the ring_hash policy does not attempt to
+  // reconnect to subchannels unless it is getting pick requests,
+  // it will need special handling to ensure that it will eventually
+  // recover from TRANSIENT_FAILURE state once the problem is resolved.
+  // Specifically, it will make sure that it is attempting to connect to
+  // at least one subchannel at any given time.  After a given subchannel
+  // fails a connection attempt, it will move on to the next subchannel
+  // in the ring.  It will keep doing this until one of the subchannels
+  // successfully connects, at which point it will report READY and stop
+  // proactively trying to connect.  The policy will remain in
+  // TRANSIENT_FAILURE until at least one subchannel becomes connected,
+  // even if subchannels are in state CONNECTING during that time.
+  //
+  // Note that we do the same thing when the policy is in state
+  // CONNECTING, just to ensure that we don't remain in CONNECTING state
+  // indefinitely if there are no new picks coming in.
+  if (internally_triggered_connection_index_.has_value() &&
+      *internally_triggered_connection_index_ == index &&
+      connection_attempt_complete) {
+    internally_triggered_connection_index_.reset();
+  }
+  if (start_connection_attempt &&
+      !internally_triggered_connection_index_.has_value()) {
+    size_t next_index = (index + 1) % num_subchannels();
+    if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
+      gpr_log(GPR_INFO,
+              "[RH %p] triggering internal connection attempt for subchannel "
+              "%p, subchannel_list %p (index %" PRIuPTR " of %" PRIuPTR ")",
+              p, subchannel(next_index)->subchannel(), this, next_index,
+              num_subchannels());
+    }
+    internally_triggered_connection_index_ = next_index;
+    subchannel(next_index)->subchannel()->RequestConnection();
+  }
 }
 
 //
 // RingHash::RingHashSubchannelData
 //
 
-void RingHash::RingHashSubchannelData::UpdateConnectivityStateLocked(
-    grpc_connectivity_state connectivity_state) {
+void RingHash::RingHashSubchannelData::ProcessConnectivityChangeLocked(
+    absl::optional<grpc_connectivity_state> old_state,
+    grpc_connectivity_state new_state) {
   RingHash* p = static_cast<RingHash*>(subchannel_list()->policy());
+  grpc_connectivity_state last_connectivity_state = GetConnectivityState();
   if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
     gpr_log(
         GPR_INFO,
@@ -614,79 +715,54 @@ void RingHash::RingHashSubchannelData::UpdateConnectivityStateLocked(
         "(index %" PRIuPTR " of %" PRIuPTR "): prev_state=%s new_state=%s",
         p, subchannel(), subchannel_list(), Index(),
         subchannel_list()->num_subchannels(),
-        ConnectivityStateName(last_connectivity_state_),
-        ConnectivityStateName(connectivity_state));
+        ConnectivityStateName(last_connectivity_state),
+        ConnectivityStateName(new_state));
   }
-  // Decide what state to report for aggregation purposes.
-  // If we haven't seen a failure since the last time we were in state
-  // READY, then we report the state change as-is.  However, once we do see
-  // a failure, we report TRANSIENT_FAILURE and do not report any subsequent
-  // state changes until we go back into state READY.
-  if (!seen_failure_since_ready_) {
-    if (connectivity_state == GRPC_CHANNEL_TRANSIENT_FAILURE) {
-      seen_failure_since_ready_ = true;
-    }
-    subchannel_list()->UpdateStateCountersLocked(last_connectivity_state_,
-                                                 connectivity_state);
-  } else {
-    if (connectivity_state == GRPC_CHANNEL_READY) {
-      seen_failure_since_ready_ = false;
-      subchannel_list()->UpdateStateCountersLocked(
-          GRPC_CHANNEL_TRANSIENT_FAILURE, connectivity_state);
-    }
-  }
-  // Record last seen connectivity state.
-  last_connectivity_state_ = connectivity_state;
-}
-
-void RingHash::RingHashSubchannelData::ProcessConnectivityChangeLocked(
-    grpc_connectivity_state connectivity_state) {
-  RingHash* p = static_cast<RingHash*>(subchannel_list()->policy());
   GPR_ASSERT(subchannel() != nullptr);
-  // Update connectivity state used by picker.
-  connectivity_state_for_picker_.store(connectivity_state,
-                                       std::memory_order_relaxed);
-  // If the new state is TRANSIENT_FAILURE, re-resolve.
-  // Only do this if we've started watching, not at startup time.
-  // Otherwise, if the subchannel was already in state TRANSIENT_FAILURE
-  // when the subchannel list was created, we'd wind up in a constant
-  // loop of re-resolution.
-  // Also attempt to reconnect.
-  if (connectivity_state == GRPC_CHANNEL_TRANSIENT_FAILURE) {
+  // If this is not the initial state notification and the new state is
+  // TRANSIENT_FAILURE or IDLE, re-resolve.
+  // Note that we don't want to do this on the initial state notification,
+  // because that would result in an endless loop of re-resolution.
+  if (old_state.has_value() && (new_state == GRPC_CHANNEL_TRANSIENT_FAILURE ||
+                                new_state == GRPC_CHANNEL_IDLE)) {
     if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
       gpr_log(GPR_INFO,
-              "[RH %p] Subchannel %p has gone into TRANSIENT_FAILURE. "
-              "Requesting re-resolution",
-              p, subchannel());
+              "[RH %p] Subchannel %p reported %s; requesting re-resolution", p,
+              subchannel(), ConnectivityStateName(new_state));
     }
     p->channel_control_helper()->RequestReresolution();
   }
-  // Update state counters.
-  UpdateConnectivityStateLocked(connectivity_state);
+  const bool connection_attempt_complete = new_state != GRPC_CHANNEL_CONNECTING;
+  // Decide what state to report for the purposes of aggregation and
+  // picker behavior.
+  // If the last recorded state was TRANSIENT_FAILURE, ignore the update
+  // unless the new state is READY.
+  bool update_status = true;
+  absl::Status status = connectivity_status();
+  if (last_connectivity_state == GRPC_CHANNEL_TRANSIENT_FAILURE &&
+      new_state != GRPC_CHANNEL_READY &&
+      new_state != GRPC_CHANNEL_TRANSIENT_FAILURE) {
+    new_state = GRPC_CHANNEL_TRANSIENT_FAILURE;
+    {
+      MutexLock lock(&mu_);
+      status = connectivity_status_;
+    }
+    update_status = false;
+  }
+  // Update state counters used for aggregation.
+  subchannel_list()->UpdateStateCountersLocked(last_connectivity_state,
+                                               new_state);
+  // Update status seen by picker if needed.
+  if (update_status) {
+    MutexLock lock(&mu_);
+    connectivity_status_ = connectivity_status();
+  }
+  // Update last seen state, also used by picker.
+  connectivity_state_.store(new_state, std::memory_order_relaxed);
   // Update the RH policy's connectivity state, creating new picker and new
   // ring.
-  bool transient_failure =
-      subchannel_list()->UpdateRingHashConnectivityStateLocked();
-  // While the ring_hash policy is reporting TRANSIENT_FAILURE, it will
-  // not be getting any pick requests from the priority policy.
-  // However, because the ring_hash policy does not attempt to
-  // reconnect to subchannels unless it is getting pick requests,
-  // it will need special handling to ensure that it will eventually
-  // recover from TRANSIENT_FAILURE state once the problem is resolved.
-  // Specifically, it will make sure that it is attempting to connect to
-  // at least one subchannel at any given time.  After a given subchannel
-  // fails a connection attempt, it will move on to the next subchannel
-  // in the ring.  It will keep doing this until one of the subchannels
-  // successfully connects, at which point it will report READY and stop
-  // proactively trying to connect.  The policy will remain in
-  // TRANSIENT_FAILURE until at least one subchannel becomes connected,
-  // even if subchannels are in state CONNECTING during that time.
-  if (transient_failure &&
-      connectivity_state == GRPC_CHANNEL_TRANSIENT_FAILURE) {
-    size_t next_index = (Index() + 1) % subchannel_list()->num_subchannels();
-    RingHashSubchannelData* next_sd = subchannel_list()->subchannel(next_index);
-    next_sd->subchannel()->AttemptToConnect();
-  }
+  subchannel_list()->UpdateRingHashConnectivityStateLocked(
+      Index(), connection_attempt_complete, status);
 }
 
 //
@@ -704,6 +780,7 @@ RingHash::~RingHash() {
     gpr_log(GPR_INFO, "[RH %p] Destroying Ring Hash policy", this);
   }
   GPR_ASSERT(subchannel_list_ == nullptr);
+  GPR_ASSERT(latest_pending_subchannel_list_ == nullptr);
 }
 
 void RingHash::ShutdownLocked() {
@@ -712,12 +789,17 @@ void RingHash::ShutdownLocked() {
   }
   shutdown_ = true;
   subchannel_list_.reset();
-  ring_.reset(DEBUG_LOCATION, "RingHash");
+  latest_pending_subchannel_list_.reset();
 }
 
-void RingHash::ResetBackoffLocked() { subchannel_list_->ResetBackoffLocked(); }
+void RingHash::ResetBackoffLocked() {
+  subchannel_list_->ResetBackoffLocked();
+  if (latest_pending_subchannel_list_ != nullptr) {
+    latest_pending_subchannel_list_->ResetBackoffLocked();
+  }
+}
 
-void RingHash::UpdateLocked(UpdateArgs args) {
+absl::Status RingHash::UpdateLocked(UpdateArgs args) {
   config_ = std::move(args.config);
   ServerAddressList addresses;
   if (args.addresses.ok()) {
@@ -725,42 +807,54 @@ void RingHash::UpdateLocked(UpdateArgs args) {
       gpr_log(GPR_INFO, "[RH %p] received update with %" PRIuPTR " addresses",
               this, args.addresses->size());
     }
-    // Filter out any address with weight 0.
-    addresses.reserve(args.addresses->size());
-    for (ServerAddress& address : *args.addresses) {
-      const ServerAddressWeightAttribute* weight_attribute =
-          static_cast<const ServerAddressWeightAttribute*>(address.GetAttribute(
-              ServerAddressWeightAttribute::kServerAddressWeightAttributeKey));
-      if (weight_attribute == nullptr || weight_attribute->weight() > 0) {
-        addresses.emplace_back(std::move(address));
-      }
-    }
+    addresses = *std::move(args.addresses);
   } else {
     if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace)) {
       gpr_log(GPR_INFO, "[RH %p] received update with addresses error: %s",
               this, args.addresses.status().ToString().c_str());
     }
-    // If we already have a subchannel list, then ignore the resolver
-    // failure and keep using the existing list.
-    if (subchannel_list_ != nullptr) return;
+    // If we already have a subchannel list, then keep using the existing
+    // list, but still report back that the update was not accepted.
+    if (subchannel_list_ != nullptr) return args.addresses.status();
   }
-  subchannel_list_ = MakeOrphanable<RingHashSubchannelList>(
-      this, &grpc_lb_ring_hash_trace, std::move(addresses), *args.args);
-  if (subchannel_list_->num_subchannels() == 0) {
-    // If the new list is empty, immediately transition to TRANSIENT_FAILURE.
-    absl::Status status =
-        args.addresses.ok() ? absl::UnavailableError(absl::StrCat(
-                                  "empty address list: ", args.resolution_note))
-                            : args.addresses.status();
-    channel_control_helper()->UpdateState(
-        GRPC_CHANNEL_TRANSIENT_FAILURE, status,
-        absl::make_unique<TransientFailurePicker>(status));
-  } else {
-    // Build the ring.
-    ring_ = subchannel_list_->MakeRing();
-    // Start watching the new list.
-    subchannel_list_->StartWatchingLocked();
+  if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace) &&
+      latest_pending_subchannel_list_ != nullptr) {
+    gpr_log(GPR_INFO, "[RH %p] replacing latest pending subchannel list %p",
+            this, latest_pending_subchannel_list_.get());
   }
+  latest_pending_subchannel_list_ = MakeRefCounted<RingHashSubchannelList>(
+      this, std::move(addresses), args.args);
+  latest_pending_subchannel_list_->StartWatchingLocked();
+  // If we have no existing list or the new list is empty, immediately
+  // promote the new list.
+  // Otherwise, do nothing; the new list will be promoted when the
+  // initial subchannel states are reported.
+  if (subchannel_list_ == nullptr ||
+      latest_pending_subchannel_list_->num_subchannels() == 0) {
+    if (GRPC_TRACE_FLAG_ENABLED(grpc_lb_ring_hash_trace) &&
+        subchannel_list_ != nullptr) {
+      gpr_log(GPR_INFO,
+              "[RH %p] empty address list, replacing subchannel list %p", this,
+              subchannel_list_.get());
+    }
+    subchannel_list_ = std::move(latest_pending_subchannel_list_);
+    // If the new list is empty, report TRANSIENT_FAILURE.
+    if (subchannel_list_->num_subchannels() == 0) {
+      absl::Status status =
+          args.addresses.ok()
+              ? absl::UnavailableError(
+                    absl::StrCat("empty address list: ", args.resolution_note))
+              : args.addresses.status();
+      channel_control_helper()->UpdateState(
+          GRPC_CHANNEL_TRANSIENT_FAILURE, status,
+          MakeRefCounted<TransientFailurePicker>(status));
+      return status;
+    }
+    // Otherwise, report IDLE.
+    subchannel_list_->UpdateRingHashConnectivityStateLocked(
+        /*index=*/0, /*connection_attempt_complete=*/false, absl::OkStatus());
+  }
+  return absl::OkStatus();
 }
 
 //
@@ -774,31 +868,23 @@ class RingHashFactory : public LoadBalancingPolicyFactory {
     return MakeOrphanable<RingHash>(std::move(args));
   }
 
-  const char* name() const override { return kRingHash; }
+  absl::string_view name() const override { return kRingHash; }
 
-  RefCountedPtr<LoadBalancingPolicy::Config> ParseLoadBalancingConfig(
-      const Json& json, grpc_error_handle* error) const override {
-    size_t min_ring_size;
-    size_t max_ring_size;
-    std::vector<grpc_error_handle> error_list;
-    ParseRingHashLbConfig(json, &min_ring_size, &max_ring_size, &error_list);
-    if (error_list.empty()) {
-      return MakeRefCounted<RingHashLbConfig>(min_ring_size, max_ring_size);
-    } else {
-      *error = GRPC_ERROR_CREATE_FROM_VECTOR(
-          "ring_hash_experimental LB policy config", &error_list);
-      return nullptr;
-    }
+  absl::StatusOr<RefCountedPtr<LoadBalancingPolicy::Config>>
+  ParseLoadBalancingConfig(const Json& json) const override {
+    auto config = LoadFromJson<RingHashConfig>(
+        json, JsonArgs(), "errors validating ring_hash LB policy config");
+    if (!config.ok()) return config.status();
+    return MakeRefCounted<RingHashLbConfig>(config->min_ring_size,
+                                            config->max_ring_size);
   }
 };
 
 }  // namespace
 
-void GrpcLbPolicyRingHashInit() {
-  LoadBalancingPolicyRegistry::Builder::RegisterLoadBalancingPolicyFactory(
-      absl::make_unique<RingHashFactory>());
+void RegisterRingHashLbPolicy(CoreConfiguration::Builder* builder) {
+  builder->lb_policy_registry()->RegisterLoadBalancingPolicyFactory(
+      std::make_unique<RingHashFactory>());
 }
 
-void GrpcLbPolicyRingHashShutdown() {}
-
 }  // namespace grpc_core