grpc 1.28.0.pre2 → 1.31.0.pre1

data/src/core/ext/filters/client_channel/lb_policy.h

@@ -24,15 +24,16 @@
 #include <functional>
 #include <iterator>
 
+#include "absl/strings/string_view.h"
+
 #include "src/core/ext/filters/client_channel/server_address.h"
 #include "src/core/ext/filters/client_channel/service_config.h"
 #include "src/core/ext/filters/client_channel/subchannel_interface.h"
 #include "src/core/lib/gprpp/map.h"
 #include "src/core/lib/gprpp/orphanable.h"
 #include "src/core/lib/gprpp/ref_counted_ptr.h"
-#include "src/core/lib/gprpp/string_view.h"
-#include "src/core/lib/iomgr/combiner.h"
 #include "src/core/lib/iomgr/polling_entity.h"
+#include "src/core/lib/iomgr/work_serializer.h"
 #include "src/core/lib/transport/connectivity_state.h"
 
 namespace grpc_core {
@@ -72,7 +73,7 @@ extern DebugOnlyTraceFlag grpc_trace_lb_policy_refcount;
 /// LoadBalacingPolicy API.
 ///
 /// Note: All methods with a "Locked" suffix must be called from the
-/// combiner passed to the constructor.
+/// work_serializer passed to the constructor.
 ///
 /// Any I/O done by the LB policy should be done under the pollset_set
 /// returned by \a interested_parties().
@@ -93,11 +94,11 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     /// Application-specific requests cost metrics.  Metric names are
     /// determined by the application.  Each value is an absolute cost
     /// (e.g. 3487 bytes of storage) associated with the request.
-    std::map<StringView, double, StringLess> request_cost;
+    std::map<absl::string_view, double, StringLess> request_cost;
     /// Application-specific resource utilization metrics.  Metric names
     /// are determined by the application.  Each value is expressed as a
     /// fraction of total resources available.
-    std::map<StringView, double, StringLess> utilization;
+    std::map<absl::string_view, double, StringLess> utilization;
   };
 
   /// Interface for accessing per-call state.
@@ -115,7 +116,17 @@ class LoadBalancingPolicy : public InternallyRefCounted {
 
     /// Returns the backend metric data returned by the server for the call,
     /// or null if no backend metric data was returned.
+    // TODO(roth): Move this out of CallState, since it should not be
+    // accessible to the picker, only to the recv_trailing_metadata_ready
+    // callback.  It should instead be in its own interface.
     virtual const BackendMetricData* GetBackendMetricData() = 0;
+
+    /// EXPERIMENTAL API.
+    /// Returns the value of the call attribute \a key.
+    /// Keys are static strings, so an attribute can be accessed by an LB
+    /// policy implementation only if it knows about the internal key.
+    /// Returns a null string_view if key not found.
+    virtual absl::string_view ExperimentalGetCallAttribute(const char* key) = 0;
   };
 
   /// Interface for accessing metadata.
@@ -123,12 +134,13 @@ class LoadBalancingPolicy : public InternallyRefCounted {
   class MetadataInterface {
    public:
     class iterator
-        : public std::iterator<std::input_iterator_tag,
-                               std::pair<StringView, StringView>,  // value_type
-                               std::ptrdiff_t,  // difference_type
-                               std::pair<StringView, StringView>*,  // pointer
-                               std::pair<StringView, StringView>&   // reference
-                               > {
+        : public std::iterator<
+              std::input_iterator_tag,
+              std::pair<absl::string_view, absl::string_view>,  // value_type
+              std::ptrdiff_t,  // difference_type
+              std::pair<absl::string_view, absl::string_view>*,  // pointer
+              std::pair<absl::string_view, absl::string_view>&   // reference
+              > {
      public:
       iterator(const MetadataInterface* md, intptr_t handle)
           : md_(md), handle_(handle) {}
@@ -155,7 +167,7 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     /// Implementations must ensure that the key and value remain alive
     /// until the call ends.  If desired, they may be allocated via
     /// CallState::Alloc().
-    virtual void Add(StringView key, StringView value) = 0;
+    virtual void Add(absl::string_view key, absl::string_view value) = 0;
 
     /// Iteration interface.
     virtual iterator begin() const = 0;
@@ -172,19 +184,21 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     friend class iterator;
 
     virtual intptr_t IteratorHandleNext(intptr_t handle) const = 0;
-    virtual std::pair<StringView /*key*/, StringView /*value */>
+    virtual std::pair<absl::string_view /*key*/, absl::string_view /*value */>
     IteratorHandleGet(intptr_t handle) const = 0;
   };
 
   /// Arguments used when picking a subchannel for a call.
   struct PickArgs {
+    /// The path of the call.  Indicates the RPC service and method name.
+    absl::string_view path;
     /// Initial metadata associated with the picking call.
     /// The LB policy may use the existing metadata to influence its routing
     /// decision, and it may add new metadata elements to be sent with the
     /// call to the chosen backend.
     MetadataInterface* initial_metadata;
     /// An interface for accessing call state.  Can be used to allocate
-    /// data associated with the call in an efficient way.
+    /// memory associated with the call in an efficient way.
     CallState* call_state;
   };
 
@@ -226,6 +240,9 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     /// does not take ownership, so any data that needs to be used after
     /// returning must be copied.
     /// The call state can be used to obtain backend metric data.
+    // TODO(roth): The arguments to this callback should be moved into a
+    // struct, so that we can later add new fields without breaking
+    // existing implementations.
     std::function<void(grpc_error*, MetadataInterface*, CallState*)>
         recv_trailing_metadata_ready;
   };
@@ -242,7 +259,7 @@ class LoadBalancingPolicy : public InternallyRefCounted {
   /// live in the LB policy object itself.
   ///
   /// Currently, pickers are always accessed from within the
-  /// client_channel data plane combiner, so they do not have to be
+  /// client_channel data plane mutex, so they do not have to be
   /// thread-safe.
   class SubchannelPicker {
    public:
@@ -254,9 +271,6 @@ class LoadBalancingPolicy : public InternallyRefCounted {
 
   /// A proxy object implemented by the client channel and used by the
   /// LB policy to communicate with the channel.
-  // TODO(juanlishen): Consider adding a mid-layer subclass that helps handle
-  // things like swapping in pending policy when it's ready. Currently, we are
-  // duplicating the logic in many subclasses.
   class ChannelControlHelper {
    public:
     ChannelControlHelper() = default;
@@ -276,7 +290,8 @@ class LoadBalancingPolicy : public InternallyRefCounted {
 
     /// Adds a trace message associated with the channel.
     enum TraceSeverity { TRACE_INFO, TRACE_WARNING, TRACE_ERROR };
-    virtual void AddTraceEvent(TraceSeverity severity, StringView message) = 0;
+    virtual void AddTraceEvent(TraceSeverity severity,
+                               absl::string_view message) = 0;
   };
 
   /// Interface for configuration data used by an LB policy implementation.
@@ -302,19 +317,15 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     UpdateArgs() = default;
     ~UpdateArgs() { grpc_channel_args_destroy(args); }
     UpdateArgs(const UpdateArgs& other);
-    UpdateArgs(UpdateArgs&& other);
+    UpdateArgs(UpdateArgs&& other) noexcept;
     UpdateArgs& operator=(const UpdateArgs& other);
-    UpdateArgs& operator=(UpdateArgs&& other);
+    UpdateArgs& operator=(UpdateArgs&& other) noexcept;
   };
 
   /// Args used to instantiate an LB policy.
   struct Args {
-    /// The combiner under which all LB policy calls will be run.
-    /// Policy does NOT take ownership of the reference to the combiner.
-    // TODO(roth): Once we have a C++-like interface for combiners, this
-    // API should change to take a smart pointer that does pass ownership
-    // of a reference.
-    Combiner* combiner = nullptr;
+    /// The work_serializer under which all LB policy calls will be run.
+    std::shared_ptr<WorkSerializer> work_serializer;
     /// Channel control helper.
     /// Note: LB policies MUST NOT call any method on the helper from
     /// their constructor.
@@ -352,7 +363,7 @@ class LoadBalancingPolicy : public InternallyRefCounted {
 
   grpc_pollset_set* interested_parties() const { return interested_parties_; }
 
-  // Note: This must be invoked while holding the combiner.
+  // Note: This must be invoked while holding the work_serializer.
   void Orphan() override;
 
   // A picker that returns PICK_QUEUE for all picks.
@@ -368,8 +379,6 @@ class LoadBalancingPolicy : public InternallyRefCounted {
     PickResult Pick(PickArgs args) override;
 
    private:
-    static void CallExitIdle(void* arg, grpc_error* error);
-
     RefCountedPtr<LoadBalancingPolicy> parent_;
     bool exit_idle_called_ = false;
   };
@@ -387,7 +396,9 @@ class LoadBalancingPolicy : public InternallyRefCounted {
   };
 
  protected:
-  Combiner* combiner() const { return combiner_; }
+  std::shared_ptr<WorkSerializer> work_serializer() const {
+    return work_serializer_;
+  }
 
   // Note: LB policies MUST NOT call any method on the helper from their
   // constructor.
@@ -399,8 +410,8 @@ class LoadBalancingPolicy : public InternallyRefCounted {
   virtual void ShutdownLocked() = 0;
 
  private:
-  /// Combiner under which LB policy actions take place.
-  Combiner* combiner_;
+  /// Work Serializer under which LB policy actions take place.
+  std::shared_ptr<WorkSerializer> work_serializer_;
   /// Owned pointer to interested parties in load balancing decisions.
   grpc_pollset_set* interested_parties_;
   /// Channel control helper.

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

@@ -0,0 +1,83 @@
+//
+// Copyright 2020 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/ext/filters/client_channel/lb_policy/address_filtering.h"
+
+#include "src/core/lib/channel/channel_args.h"
+
+#define GRPC_ARG_HIERARCHICAL_PATH "grpc.internal.address.hierarchical_path"
+
+namespace grpc_core {
+
+namespace {
+
+void* HierarchicalPathCopy(void* p) {
+  std::vector<std::string>* path = static_cast<std::vector<std::string>*>(p);
+  return static_cast<void*>(new std::vector<std::string>(*path));
+}
+
+void HierarchicalPathDestroy(void* p) {
+  std::vector<std::string>* path = static_cast<std::vector<std::string>*>(p);
+  delete path;
+}
+
+int HierarchicalPathCompare(void* p1, void* p2) {
+  std::vector<std::string>* path1 = static_cast<std::vector<std::string>*>(p1);
+  std::vector<std::string>* path2 = static_cast<std::vector<std::string>*>(p2);
+  for (size_t i = 0; i < path1->size(); ++i) {
+    if (path2->size() == i) return 1;
+    int r = (*path1)[i].compare((*path2)[i]);
+    if (r != 0) return r;
+  }
+  if (path2->size() > path1->size()) return -1;
+  return 0;
+}
+
+const grpc_arg_pointer_vtable hierarchical_path_arg_vtable = {
+    HierarchicalPathCopy, HierarchicalPathDestroy, HierarchicalPathCompare};
+
+}  // namespace
+
+grpc_arg MakeHierarchicalPathArg(const std::vector<std::string>& path) {
+  return grpc_channel_arg_pointer_create(
+      const_cast<char*>(GRPC_ARG_HIERARCHICAL_PATH),
+      const_cast<std::vector<std::string>*>(&path),
+      &hierarchical_path_arg_vtable);
+}
+
+HierarchicalAddressMap MakeHierarchicalAddressMap(
+    const ServerAddressList& addresses) {
+  HierarchicalAddressMap result;
+  for (const ServerAddress& address : addresses) {
+    auto* path = grpc_channel_args_find_pointer<std::vector<std::string>>(
+        address.args(), GRPC_ARG_HIERARCHICAL_PATH);
+    if (path == nullptr || path->empty()) continue;
+    auto it = path->begin();
+    ServerAddressList& target_list = result[*it];
+    ++it;
+    std::vector<std::string> remaining_path(it, path->end());
+    const char* name_to_remove = GRPC_ARG_HIERARCHICAL_PATH;
+    grpc_arg new_arg = MakeHierarchicalPathArg(remaining_path);
+    grpc_channel_args* new_args = grpc_channel_args_copy_and_add_and_remove(
+        address.args(), &name_to_remove, 1, &new_arg, 1);
+    target_list.emplace_back(address.address(), new_args);
+  }
+  return result;
+}
+
+}  // namespace grpc_core

data/src/core/ext/filters/client_channel/lb_policy/address_filtering.h

@@ -0,0 +1,99 @@
+//
+// Copyright 2020 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H
+
+#include <grpc/support/port_platform.h>
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "absl/strings/string_view.h"
+
+#include "src/core/ext/filters/client_channel/server_address.h"
+
+// The resolver returns a flat list of addresses.  When a hierarchy of
+// LB policies is in use, each leaf of the hierarchy will need a
+// different subset of those addresses.  This library provides a
+// mechanism for determining which address is passed to which leaf
+// policy.
+//
+// Each address will have an associated path that indicates which child
+// it should be sent to at each level of the hierarchy to wind up at the
+// right leaf policy.  Each LB policy will look at the first element of
+// the path of each address to determine which child to send the address
+// to.  It will then remove that first element when passing the address
+// down to its child.
+//
+// For example, consider the following LB policy hierarchy:
+//
+// - priority
+//   - child0 (weighted_target)
+//     - localityA (round_robin)
+//     - localityB (round_robin)
+//   - child1 (weighted_target)
+//     - localityC (round_robin)
+//     - localityD (round_robin)
+//
+// Now consider the following addresses:
+// - 10.0.0.1:80 path=["child0", "localityA"]
+// - 10.0.0.2:80 path=["child0", "localityB"]
+// - 10.0.0.3:80 path=["child1", "localityC"]
+// - 10.0.0.4:80 path=["child1", "localityD"]
+//
+// The priority policy will split this up into two lists, one for each
+// of its children:
+// - child0:
+//   - 10.0.0.1:80 path=["localityA"]
+//   - 10.0.0.2:80 path=["localityB"]
+// - child1:
+//   - 10.0.0.3:80 path=["localityC"]
+//   - 10.0.0.4:80 path=["localityD"]
+//
+// The weighted_target policy for child0 will split its list up into two
+// lists, one for each of its children:
+// - localityA:
+//   - 10.0.0.1:80 path=[]
+// - localityB:
+//   - 10.0.0.2:80 path=[]
+//
+// Similarly, the weighted_target policy for child1 will split its list
+// up into two lists, one for each of its children:
+// - localityC:
+//   - 10.0.0.3:80 path=[]
+// - localityD:
+//   - 10.0.0.4:80 path=[]
+
+namespace grpc_core {
+
+// Constructs a channel arg containing the hierarchical path
+// to be associated with an address.
+grpc_arg MakeHierarchicalPathArg(const std::vector<std::string>& path);
+
+// A map from the next path element to the addresses that fall under
+// that path element.
+using HierarchicalAddressMap = std::map<std::string, ServerAddressList>;
+
+// Splits up the addresses into a separate list for each child.
+HierarchicalAddressMap MakeHierarchicalAddressMap(
+    const ServerAddressList& addresses);
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H \
+        */

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

@@ -0,0 +1,297 @@
+//
+// Copyright 2018 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#include <grpc/support/port_platform.h>
+
+#include <cstring>
+
+#include "src/core/ext/filters/client_channel/lb_policy/child_policy_handler.h"
+
+#include "absl/strings/str_cat.h"
+
+#include "src/core/ext/filters/client_channel/lb_policy_registry.h"
+
+namespace grpc_core {
+
+//
+// ChildPolicyHandler::Helper
+//
+
+class ChildPolicyHandler::Helper
+    : public LoadBalancingPolicy::ChannelControlHelper {
+ public:
+  explicit Helper(RefCountedPtr<ChildPolicyHandler> parent)
+      : parent_(std::move(parent)) {}
+
+  ~Helper() { parent_.reset(DEBUG_LOCATION, "Helper"); }
+
+  RefCountedPtr<SubchannelInterface> CreateSubchannel(
+      const grpc_channel_args& args) override {
+    if (parent_->shutting_down_) return nullptr;
+    if (!CalledByCurrentChild() && !CalledByPendingChild()) return nullptr;
+    return parent_->channel_control_helper()->CreateSubchannel(args);
+  }
+
+  void UpdateState(grpc_connectivity_state state,
+                   std::unique_ptr<SubchannelPicker> picker) override {
+    if (parent_->shutting_down_) return;
+    // If this request is from the pending child policy, ignore it until
+    // it reports something other than CONNECTING, at which point we swap it
+    // into place.
+    if (CalledByPendingChild()) {
+      if (GRPC_TRACE_FLAG_ENABLED(*(parent_->tracer_))) {
+        gpr_log(GPR_INFO,
+                "[child_policy_handler %p] helper %p: pending child policy %p "
+                "reports state=%s",
+                parent_.get(), this, child_, ConnectivityStateName(state));
+      }
+      if (state == GRPC_CHANNEL_CONNECTING) return;
+      grpc_pollset_set_del_pollset_set(
+          parent_->child_policy_->interested_parties(),
+          parent_->interested_parties());
+      parent_->child_policy_ = std::move(parent_->pending_child_policy_);
+    } else if (!CalledByCurrentChild()) {
+      // This request is from an outdated child, so ignore it.
+      return;
+    }
+    parent_->channel_control_helper()->UpdateState(state, std::move(picker));
+  }
+
+  void RequestReresolution() override {
+    if (parent_->shutting_down_) return;
+    // Only forward re-resolution requests from the most recent child,
+    // since that's the one that will be receiving any update we receive
+    // from the resolver.
+    const LoadBalancingPolicy* latest_child_policy =
+        parent_->pending_child_policy_ != nullptr
+            ? parent_->pending_child_policy_.get()
+            : parent_->child_policy_.get();
+    if (child_ != latest_child_policy) return;
+    if (GRPC_TRACE_FLAG_ENABLED(*(parent_->tracer_))) {
+      gpr_log(GPR_INFO, "[child_policy_handler %p] started name re-resolving",
+              parent_.get());
+    }
+    parent_->channel_control_helper()->RequestReresolution();
+  }
+
+  void AddTraceEvent(TraceSeverity severity,
+                     absl::string_view message) override {
+    if (parent_->shutting_down_) return;
+    if (!CalledByPendingChild() && !CalledByCurrentChild()) return;
+    parent_->channel_control_helper()->AddTraceEvent(severity, message);
+  }
+
+  void set_child(LoadBalancingPolicy* child) { child_ = child; }
+
+ private:
+  bool CalledByPendingChild() const {
+    GPR_ASSERT(child_ != nullptr);
+    return child_ == parent_->pending_child_policy_.get();
+  }
+
+  bool CalledByCurrentChild() const {
+    GPR_ASSERT(child_ != nullptr);
+    return child_ == parent_->child_policy_.get();
+  };
+
+  RefCountedPtr<ChildPolicyHandler> parent_;
+  LoadBalancingPolicy* child_ = nullptr;
+};
+
+//
+// ChildPolicyHandler
+//
+
+void ChildPolicyHandler::ShutdownLocked() {
+  if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+    gpr_log(GPR_INFO, "[child_policy_handler %p] shutting down", this);
+  }
+  shutting_down_ = true;
+  if (child_policy_ != nullptr) {
+    if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+      gpr_log(GPR_INFO, "[child_policy_handler %p] shutting down lb_policy %p",
+              this, child_policy_.get());
+    }
+    grpc_pollset_set_del_pollset_set(child_policy_->interested_parties(),
+                                     interested_parties());
+    child_policy_.reset();
+  }
+  if (pending_child_policy_ != nullptr) {
+    if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+      gpr_log(GPR_INFO,
+              "[child_policy_handler %p] shutting down pending lb_policy %p",
+              this, pending_child_policy_.get());
+    }
+    grpc_pollset_set_del_pollset_set(
+        pending_child_policy_->interested_parties(), interested_parties());
+    pending_child_policy_.reset();
+  }
+}
+
+void ChildPolicyHandler::UpdateLocked(UpdateArgs args) {
+  // If the child policy name changes, we need to create a new child
+  // policy.  When this happens, we leave child_policy_ as-is and store
+  // the new child policy in pending_child_policy_.  Once the new child
+  // policy transitions into state READY, we swap it into child_policy_,
+  // replacing the original child policy.  So pending_child_policy_ is
+  // non-null only between when we apply an update that changes the child
+  // policy name and when the new child reports state READY.
+  //
+  // Updates can arrive at any point during this transition.  We always
+  // apply updates relative to the most recently created child policy,
+  // even if the most recent one is still in pending_child_policy_.  This
+  // is true both when applying the updates to an existing child policy
+  // and when determining whether we need to create a new policy.
+  //
+  // As a result of this, there are several cases to consider here:
+  //
+  // 1. We have no existing child policy (i.e., this is the first update
+  //    we receive after being created; in this case, both child_policy_
+  //    and pending_child_policy_ are null).  In this case, we create a
+  //    new child policy and store it in child_policy_.
+  //
+  // 2. We have an existing child policy and have no pending child policy
+  //    from a previous update (i.e., either there has not been a
+  //    previous update that changed the policy name, or we have already
+  //    finished swapping in the new policy; in this case, child_policy_
+  //    is non-null but pending_child_policy_ is null).  In this case:
+  //    a. If going from the current config to the new config does not
+  //       require a new policy, then we update the existing child policy.
+  //    b. If going from the current config to the new config does require a
+  //       new policy, we create a new policy.  The policy will be stored in
+  //       pending_child_policy_ and will later be swapped into
+  //       child_policy_ by the helper when the new child transitions
+  //       into state READY.
+  //
+  // 3. We have an existing child policy and have a pending child policy
+  //    from a previous update (i.e., a previous update set
+  //    pending_child_policy_ as per case 2b above and that policy has
+  //    not yet transitioned into state READY and been swapped into
+  //    child_policy_; in this case, both child_policy_ and
+  //    pending_child_policy_ are non-null).  In this case:
+  //    a. If going from the current config to the new config does not
+  //       require a new policy, then we update the existing pending
+  //       child policy.
+  //    b. If going from the current config to the new config does require a
+  //       new child policy, then we create a new policy.  The new
+  //       policy is stored in pending_child_policy_ (replacing the one
+  //       that was there before, which will be immediately shut down)
+  //       and will later be swapped into child_policy_ by the helper
+  //       when the new child transitions into state READY.
+  const bool create_policy =
+      // case 1
+      child_policy_ == nullptr ||
+      // cases 2b and 3b
+      ConfigChangeRequiresNewPolicyInstance(current_config_.get(),
+                                            args.config.get());
+  current_config_ = args.config;
+  LoadBalancingPolicy* policy_to_update = nullptr;
+  if (create_policy) {
+    // Cases 1, 2b, and 3b: create a new child policy.
+    // If child_policy_ is null, we set it (case 1), else we set
+    // pending_child_policy_ (cases 2b and 3b).
+    // TODO(roth): In cases 2b and 3b, we should start a timer here, so
+    // that there's an upper bound on the amount of time it takes us to
+    // switch to the new policy, even if the new policy stays in
+    // CONNECTING for a very long period of time.
+    if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+      gpr_log(GPR_INFO,
+              "[child_policy_handler %p] creating new %schild policy %s", this,
+              child_policy_ == nullptr ? "" : "pending ", args.config->name());
+    }
+    auto& lb_policy =
+        child_policy_ == nullptr ? child_policy_ : pending_child_policy_;
+    lb_policy = CreateChildPolicy(args.config->name(), *args.args);
+    policy_to_update = lb_policy.get();
+  } else {
+    // Cases 2a and 3a: update an existing policy.
+    // If we have a pending child policy, send the update to the pending
+    // policy (case 3a), else send it to the current policy (case 2a).
+    policy_to_update = pending_child_policy_ != nullptr
+                           ? pending_child_policy_.get()
+                           : child_policy_.get();
+  }
+  GPR_ASSERT(policy_to_update != nullptr);
+  // Update the policy.
+  if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+    gpr_log(GPR_INFO, "[child_policy_handler %p] updating %schild policy %p",
+            this,
+            policy_to_update == pending_child_policy_.get() ? "pending " : "",
+            policy_to_update);
+  }
+  policy_to_update->UpdateLocked(std::move(args));
+}
+
+void ChildPolicyHandler::ExitIdleLocked() {
+  if (child_policy_ != nullptr) {
+    child_policy_->ExitIdleLocked();
+    if (pending_child_policy_ != nullptr) {
+      pending_child_policy_->ExitIdleLocked();
+    }
+  }
+}
+
+void ChildPolicyHandler::ResetBackoffLocked() {
+  if (child_policy_ != nullptr) {
+    child_policy_->ResetBackoffLocked();
+    if (pending_child_policy_ != nullptr) {
+      pending_child_policy_->ResetBackoffLocked();
+    }
+  }
+}
+
+OrphanablePtr<LoadBalancingPolicy> ChildPolicyHandler::CreateChildPolicy(
+    const char* child_policy_name, const grpc_channel_args& args) {
+  Helper* helper = new Helper(Ref(DEBUG_LOCATION, "Helper"));
+  LoadBalancingPolicy::Args lb_policy_args;
+  lb_policy_args.work_serializer = work_serializer();
+  lb_policy_args.channel_control_helper =
+      std::unique_ptr<ChannelControlHelper>(helper);
+  lb_policy_args.args = &args;
+  OrphanablePtr<LoadBalancingPolicy> lb_policy =
+      CreateLoadBalancingPolicy(child_policy_name, std::move(lb_policy_args));
+  if (GPR_UNLIKELY(lb_policy == nullptr)) {
+    gpr_log(GPR_ERROR, "could not create LB policy \"%s\"", child_policy_name);
+    return nullptr;
+  }
+  helper->set_child(lb_policy.get());
+  if (GRPC_TRACE_FLAG_ENABLED(*tracer_)) {
+    gpr_log(GPR_INFO,
+            "[child_policy_handler %p] created new LB policy \"%s\" (%p)", this,
+            child_policy_name, lb_policy.get());
+  }
+  channel_control_helper()->AddTraceEvent(
+      ChannelControlHelper::TRACE_INFO,
+      absl::StrCat("Created new LB policy \"", child_policy_name, "\""));
+  grpc_pollset_set_add_pollset_set(lb_policy->interested_parties(),
+                                   interested_parties());
+  return lb_policy;
+}
+
+bool ChildPolicyHandler::ConfigChangeRequiresNewPolicyInstance(
+    LoadBalancingPolicy::Config* old_config,
+    LoadBalancingPolicy::Config* new_config) const {
+  return strcmp(old_config->name(), new_config->name()) != 0;
+}
+
+OrphanablePtr<LoadBalancingPolicy>
+ChildPolicyHandler::CreateLoadBalancingPolicy(
+    const char* name, LoadBalancingPolicy::Args args) const {
+  return LoadBalancingPolicyRegistry::CreateLoadBalancingPolicy(
+      name, std::move(args));
+}
+
+}  // namespace grpc_core