grpc 1.19.0 → 1.20.0.pre1

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

@@ -71,11 +71,11 @@ class SubchannelNode : public BaseNode {
   grpc_json* RenderJson() override;
 
   // proxy methods to composed classes.
-  void AddTraceEvent(ChannelTrace::Severity severity, grpc_slice data) {
+  void AddTraceEvent(ChannelTrace::Severity severity, const grpc_slice& data) {
     trace_.AddTraceEvent(severity, data);
   }
   void AddTraceEventWithReference(ChannelTrace::Severity severity,
-                                  grpc_slice data,
+                                  const grpc_slice& data,
                                   RefCountedPtr<BaseNode> referenced_channel) {
     trace_.AddTraceEventWithReference(severity, data,
                                       std::move(referenced_channel));

data/src/core/ext/filters/client_channel/client_channel_factory.cc

@@ -21,47 +21,35 @@
 #include "src/core/ext/filters/client_channel/client_channel_factory.h"
 #include "src/core/lib/channel/channel_args.h"
 
-void grpc_client_channel_factory_ref(grpc_client_channel_factory* factory) {
-  factory->vtable->ref(factory);
-}
+// Channel arg key for client channel factory.
+#define GRPC_ARG_CLIENT_CHANNEL_FACTORY "grpc.client_channel_factory"
 
-void grpc_client_channel_factory_unref(grpc_client_channel_factory* factory) {
-  factory->vtable->unref(factory);
-}
+namespace grpc_core {
 
-grpc_core::Subchannel* grpc_client_channel_factory_create_subchannel(
-    grpc_client_channel_factory* factory, const grpc_channel_args* args) {
-  return factory->vtable->create_subchannel(factory, args);
-}
+namespace {
 
-grpc_channel* grpc_client_channel_factory_create_channel(
-    grpc_client_channel_factory* factory, const char* target,
-    grpc_client_channel_type type, const grpc_channel_args* args) {
-  return factory->vtable->create_client_channel(factory, target, type, args);
+void* factory_arg_copy(void* f) { return f; }
+void factory_arg_destroy(void* f) {}
+int factory_arg_cmp(void* factory1, void* factory2) {
+  return GPR_ICMP(factory1, factory2);
 }
+const grpc_arg_pointer_vtable factory_arg_vtable = {
+    factory_arg_copy, factory_arg_destroy, factory_arg_cmp};
 
-static void* factory_arg_copy(void* factory) {
-  grpc_client_channel_factory_ref(
-      static_cast<grpc_client_channel_factory*>(factory));
-  return factory;
-}
+}  // namespace
 
-static void factory_arg_destroy(void* factory) {
-  grpc_client_channel_factory_unref(
-      static_cast<grpc_client_channel_factory*>(factory));
+grpc_arg ClientChannelFactory::CreateChannelArg(ClientChannelFactory* factory) {
+  return grpc_channel_arg_pointer_create(
+      const_cast<char*>(GRPC_ARG_CLIENT_CHANNEL_FACTORY), factory,
+      &factory_arg_vtable);
 }
 
-static int factory_arg_cmp(void* factory1, void* factory2) {
-  if (factory1 < factory2) return -1;
-  if (factory1 > factory2) return 1;
-  return 0;
+ClientChannelFactory* ClientChannelFactory::GetFromChannelArgs(
+    const grpc_channel_args* args) {
+  const grpc_arg* arg =
+      grpc_channel_args_find(args, GRPC_ARG_CLIENT_CHANNEL_FACTORY);
+  if (arg == nullptr || arg->type != GRPC_ARG_POINTER) return nullptr;
+  return static_cast<ClientChannelFactory*>(arg->value.pointer.p);
 }
 
-static const grpc_arg_pointer_vtable factory_arg_vtable = {
-    factory_arg_copy, factory_arg_destroy, factory_arg_cmp};
-
-grpc_arg grpc_client_channel_factory_create_channel_arg(
-    grpc_client_channel_factory* factory) {
-  return grpc_channel_arg_pointer_create((char*)GRPC_ARG_CLIENT_CHANNEL_FACTORY,
-                                         factory, &factory_arg_vtable);
-}
+}  // namespace grpc_core

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

@@ -24,51 +24,32 @@
 #include <grpc/impl/codegen/grpc_types.h>
 
 #include "src/core/ext/filters/client_channel/subchannel.h"
-#include "src/core/lib/channel/channel_stack.h"
+#include "src/core/lib/gprpp/abstract.h"
 
-// Channel arg key for client channel factory.
-#define GRPC_ARG_CLIENT_CHANNEL_FACTORY "grpc.client_channel_factory"
+namespace grpc_core {
 
-typedef struct grpc_client_channel_factory grpc_client_channel_factory;
-typedef struct grpc_client_channel_factory_vtable
-    grpc_client_channel_factory_vtable;
+class ClientChannelFactory {
+ public:
+  virtual ~ClientChannelFactory() = default;
 
-typedef enum {
-  GRPC_CLIENT_CHANNEL_TYPE_REGULAR, /** for the user-level regular calls */
-  GRPC_CLIENT_CHANNEL_TYPE_LOAD_BALANCING, /** for communication with a load
-                                              balancing service */
-} grpc_client_channel_type;
+  // Creates a subchannel with the specified args.
+  virtual Subchannel* CreateSubchannel(const grpc_channel_args* args)
+      GRPC_ABSTRACT;
 
-/** Constructor for new configured channels.
-    Creating decorators around this type is encouraged to adapt behavior. */
-struct grpc_client_channel_factory {
-  const grpc_client_channel_factory_vtable* vtable;
-};
-
-struct grpc_client_channel_factory_vtable {
-  void (*ref)(grpc_client_channel_factory* factory);
-  void (*unref)(grpc_client_channel_factory* factory);
-  grpc_core::Subchannel* (*create_subchannel)(
-      grpc_client_channel_factory* factory, const grpc_channel_args* args);
-  grpc_channel* (*create_client_channel)(grpc_client_channel_factory* factory,
-                                         const char* target,
-                                         grpc_client_channel_type type,
-                                         const grpc_channel_args* args);
-};
+  // Creates a channel for the specified target with the specified args.
+  virtual grpc_channel* CreateChannel(
+      const char* target, const grpc_channel_args* args) GRPC_ABSTRACT;
 
-void grpc_client_channel_factory_ref(grpc_client_channel_factory* factory);
-void grpc_client_channel_factory_unref(grpc_client_channel_factory* factory);
+  // Returns a channel arg containing the specified factory.
+  static grpc_arg CreateChannelArg(ClientChannelFactory* factory);
 
-/** Create a new grpc_subchannel */
-grpc_core::Subchannel* grpc_client_channel_factory_create_subchannel(
-    grpc_client_channel_factory* factory, const grpc_channel_args* args);
+  // Returns the factory from args, or null if not found.
+  static ClientChannelFactory* GetFromChannelArgs(
+      const grpc_channel_args* args);
 
-/** Create a new grpc_channel */
-grpc_channel* grpc_client_channel_factory_create_channel(
-    grpc_client_channel_factory* factory, const char* target,
-    grpc_client_channel_type type, const grpc_channel_args* args);
+  GRPC_ABSTRACT_BASE_CLASS
+};
 
-grpc_arg grpc_client_channel_factory_create_channel_arg(
-    grpc_client_channel_factory* factory);
+}  // namespace grpc_core
 
 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_CLIENT_CHANNEL_FACTORY_H */

data/src/core/ext/filters/client_channel/global_subchannel_pool.cc

@@ -66,10 +66,13 @@ Subchannel* GlobalSubchannelPool::RegisterSubchannel(SubchannelKey* key,
     // Check to see if a subchannel already exists.
     c = static_cast<Subchannel*>(grpc_avl_get(old_map, key, nullptr));
     if (c != nullptr) {
-      // The subchannel already exists. Reuse it.
+      // The subchannel already exists. Try to reuse it.
       c = GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(c, "subchannel_register+reuse");
-      GRPC_SUBCHANNEL_UNREF(constructed, "subchannel_register+found_existing");
-      // Exit the CAS loop without modifying the shared map.
+      if (c != nullptr) {
+        GRPC_SUBCHANNEL_UNREF(constructed,
+                              "subchannel_register+found_existing");
+        // Exit the CAS loop without modifying the shared map.
+      }  // Else, reuse failed, so retry CAS loop.
     } else {
       // There hasn't been such subchannel. Add one.
       // Note that we should ref the old map first because grpc_avl_add() will
@@ -128,7 +131,7 @@ Subchannel* GlobalSubchannelPool::FindSubchannel(SubchannelKey* key) {
   grpc_avl index = grpc_avl_ref(subchannel_map_, nullptr);
   gpr_mu_unlock(&mu_);
   Subchannel* c = static_cast<Subchannel*>(grpc_avl_get(index, key, nullptr));
-  if (c != nullptr) GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(c, "found_from_pool");
+  if (c != nullptr) c = GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(c, "found_from_pool");
   grpc_avl_unref(index, nullptr);
   return c;
 }

data/src/core/ext/filters/client_channel/http_connect_handshaker.cc

@@ -144,7 +144,7 @@ void HttpConnectHandshaker::OnWriteDone(void* arg, grpc_error* error) {
     // The read callback inherits our ref to the handshaker.
     grpc_endpoint_read(handshaker->args_->endpoint,
                        handshaker->args_->read_buffer,
-                       &handshaker->response_read_closure_);
+                       &handshaker->response_read_closure_, /*urgent=*/true);
     gpr_mu_unlock(&handshaker->mu_);
   }
 }
@@ -207,7 +207,7 @@ void HttpConnectHandshaker::OnReadDone(void* arg, grpc_error* error) {
     grpc_slice_buffer_reset_and_unref_internal(handshaker->args_->read_buffer);
     grpc_endpoint_read(handshaker->args_->endpoint,
                        handshaker->args_->read_buffer,
-                       &handshaker->response_read_closure_);
+                       &handshaker->response_read_closure_, /*urgent=*/true);
     gpr_mu_unlock(&handshaker->mu_);
     return;
   }

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

@@ -23,11 +23,45 @@
 #include "src/core/ext/filters/client_channel/lb_policy_registry.h"
 #include "src/core/lib/iomgr/combiner.h"
 
-grpc_core::DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(
-    false, "lb_policy_refcount");
-
 namespace grpc_core {
 
+DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(false, "lb_policy_refcount");
+
+//
+// LoadBalancingPolicy
+//
+
+LoadBalancingPolicy::LoadBalancingPolicy(Args args, intptr_t initial_refcount)
+    : InternallyRefCounted(&grpc_trace_lb_policy_refcount, initial_refcount),
+      combiner_(GRPC_COMBINER_REF(args.combiner, "lb_policy")),
+      interested_parties_(grpc_pollset_set_create()),
+      channel_control_helper_(std::move(args.channel_control_helper)) {}
+
+LoadBalancingPolicy::~LoadBalancingPolicy() {
+  grpc_pollset_set_destroy(interested_parties_);
+  GRPC_COMBINER_UNREF(combiner_, "lb_policy");
+}
+
+void LoadBalancingPolicy::Orphan() {
+  // Invoke ShutdownAndUnrefLocked() inside of the combiner.
+  // TODO(roth): Is this actually needed?  We should already be in the
+  // combiner here.  Note that if we directly call ShutdownLocked(),
+  // then we can probably remove the hack whereby the helper is
+  // destroyed at shutdown instead of at destruction.
+  GRPC_CLOSURE_SCHED(
+      GRPC_CLOSURE_CREATE(&LoadBalancingPolicy::ShutdownAndUnrefLocked, this,
+                          grpc_combiner_scheduler(combiner_)),
+      GRPC_ERROR_NONE);
+}
+
+void LoadBalancingPolicy::ShutdownAndUnrefLocked(void* arg,
+                                                 grpc_error* ignored) {
+  LoadBalancingPolicy* policy = static_cast<LoadBalancingPolicy*>(arg);
+  policy->ShutdownLocked();
+  policy->channel_control_helper_.reset();
+  policy->Unref();
+}
+
 grpc_json* LoadBalancingPolicy::ParseLoadBalancingConfig(
     const grpc_json* lb_config_array) {
   if (lb_config_array == nullptr || lb_config_array->type != GRPC_JSON_ARRAY) {
@@ -54,35 +88,78 @@ grpc_json* LoadBalancingPolicy::ParseLoadBalancingConfig(
   return nullptr;
 }
 
-LoadBalancingPolicy::LoadBalancingPolicy(Args args)
-    : InternallyRefCounted(&grpc_trace_lb_policy_refcount),
-      combiner_(GRPC_COMBINER_REF(args.combiner, "lb_policy")),
-      client_channel_factory_(args.client_channel_factory),
-      subchannel_pool_(std::move(args.subchannel_pool)),
-      interested_parties_(grpc_pollset_set_create()),
-      request_reresolution_(nullptr) {}
+//
+// LoadBalancingPolicy::UpdateArgs
+//
 
-LoadBalancingPolicy::~LoadBalancingPolicy() {
-  grpc_pollset_set_destroy(interested_parties_);
-  GRPC_COMBINER_UNREF(combiner_, "lb_policy");
+LoadBalancingPolicy::UpdateArgs::UpdateArgs(const UpdateArgs& other) {
+  addresses = other.addresses;
+  config = other.config;
+  args = grpc_channel_args_copy(other.args);
 }
 
-void LoadBalancingPolicy::TryReresolutionLocked(
-    grpc_core::TraceFlag* grpc_lb_trace, grpc_error* error) {
-  if (request_reresolution_ != nullptr) {
-    GRPC_CLOSURE_SCHED(request_reresolution_, error);
-    request_reresolution_ = nullptr;
-    if (grpc_lb_trace->enabled()) {
-      gpr_log(GPR_INFO,
-              "%s %p: scheduling re-resolution closure with error=%s.",
-              grpc_lb_trace->name(), this, grpc_error_string(error));
-    }
-  } else {
-    if (grpc_lb_trace->enabled()) {
-      gpr_log(GPR_INFO, "%s %p: no available re-resolution closure.",
-              grpc_lb_trace->name(), this);
-    }
+LoadBalancingPolicy::UpdateArgs::UpdateArgs(UpdateArgs&& other) {
+  addresses = std::move(other.addresses);
+  config = std::move(other.config);
+  // TODO(roth): Use std::move() once channel args is converted to C++.
+  args = other.args;
+  other.args = nullptr;
+}
+
+LoadBalancingPolicy::UpdateArgs& LoadBalancingPolicy::UpdateArgs::operator=(
+    const UpdateArgs& other) {
+  addresses = other.addresses;
+  config = other.config;
+  grpc_channel_args_destroy(args);
+  args = grpc_channel_args_copy(other.args);
+  return *this;
+}
+
+LoadBalancingPolicy::UpdateArgs& LoadBalancingPolicy::UpdateArgs::operator=(
+    UpdateArgs&& other) {
+  addresses = std::move(other.addresses);
+  config = std::move(other.config);
+  // TODO(roth): Use std::move() once channel args is converted to C++.
+  grpc_channel_args_destroy(args);
+  args = other.args;
+  other.args = nullptr;
+  return *this;
+}
+
+//
+// LoadBalancingPolicy::QueuePicker
+//
+
+LoadBalancingPolicy::PickResult LoadBalancingPolicy::QueuePicker::Pick(
+    PickArgs* pick, grpc_error** error) {
+  // We invoke the parent's ExitIdleLocked() via a closure instead
+  // of doing it directly here, for two reasons:
+  // 1. ExitIdleLocked() may cause the policy's state to change and
+  //    a new picker to be delivered to the channel.  If that new
+  //    picker is delivered before ExitIdleLocked() returns, then by
+  //    the time this function returns, the pick will already have
+  //    been processed, and we'll be trying to re-process the same
+  //    pick again, leading to a crash.
+  // 2. In a subsequent PR, we will split the data plane and control
+  //    plane synchronization into separate combiners, at which
+  //    point this will need to hop from the data plane combiner into
+  //    the control plane combiner.
+  if (!exit_idle_called_) {
+    exit_idle_called_ = true;
+    parent_->Ref().release();  // ref held by closure.
+    GRPC_CLOSURE_SCHED(
+        GRPC_CLOSURE_CREATE(&CallExitIdle, parent_.get(),
+                            grpc_combiner_scheduler(parent_->combiner())),
+        GRPC_ERROR_NONE);
   }
+  return PICK_QUEUE;
+}
+
+void LoadBalancingPolicy::QueuePicker::CallExitIdle(void* arg,
+                                                    grpc_error* error) {
+  LoadBalancingPolicy* parent = static_cast<LoadBalancingPolicy*>(arg);
+  parent->ExitIdleLocked();
+  parent->Unref();
 }
 
 }  // namespace grpc_core

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

@@ -22,9 +22,9 @@
 #include <grpc/support/port_platform.h>
 
 #include "src/core/ext/filters/client_channel/client_channel_channelz.h"
-#include "src/core/ext/filters/client_channel/client_channel_factory.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.h"
-#include "src/core/ext/filters/client_channel/subchannel_pool_interface.h"
 #include "src/core/lib/gprpp/abstract.h"
 #include "src/core/lib/gprpp/orphanable.h"
 #include "src/core/lib/gprpp/ref_counted_ptr.h"
@@ -38,13 +38,199 @@ namespace grpc_core {
 
 /// Interface for load balancing policies.
 ///
+/// The following concepts are used here:
+///
+/// Channel: An abstraction that manages connections to backend servers
+///   on behalf of a client application.  The application creates a channel
+///   for a given server name and then sends RPCs on it, and the channel
+///   figures out which backend server to send each RPC to.  A channel
+///   contains a resolver, a load balancing policy (or a tree of LB policies),
+///   and a set of one or more subchannels.
+///
+/// Subchannel: A subchannel represents a connection to one backend server.
+///   The LB policy decides which subchannels to create, manages the
+///   connectivity state of those subchannels, and decides which subchannel
+///   to send any given RPC to.
+///
+/// Resolver: A plugin that takes a gRPC server URI and resolves it to a
+///   list of one or more addresses and a service config, as described
+///   in https://github.com/grpc/grpc/blob/master/doc/naming.md.  See
+///   resolver.h for the resolver API.
+///
+/// Load Balancing (LB) Policy: A plugin that takes a list of addresses
+///   from the resolver, maintains and manages a subchannel for each
+///   backend address, and decides which subchannel to send each RPC on.
+///   An LB policy has two parts:
+///   - A LoadBalancingPolicy, which deals with the control plane work of
+///     managing subchannels.
+///   - A SubchannelPicker, which handles the data plane work of
+///     determining which subchannel a given RPC should be sent on.
+
+/// LoadBalacingPolicy API.
+///
 /// Note: All methods with a "Locked" suffix must be called from the
 /// combiner passed to the constructor.
 ///
 /// Any I/O done by the LB policy should be done under the pollset_set
 /// returned by \a interested_parties().
+// TODO(roth): Once we move to EventManager-based polling, remove the
+// interested_parties() hooks from the API.
 class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
  public:
+  /// Arguments used when picking a subchannel for an RPC.
+  struct PickArgs {
+    ///
+    /// Input parameters.
+    ///
+    /// 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.
+    // TODO(roth): Provide a more generic metadata API here.
+    grpc_metadata_batch* initial_metadata = nullptr;
+    /// Storage for LB token in \a initial_metadata, or nullptr if not used.
+    // TODO(roth): Remove this from the API.  Maybe have the LB policy
+    // allocate this on the arena instead?
+    grpc_linked_mdelem lb_token_mdelem_storage;
+    ///
+    /// Output parameters.
+    ///
+    /// Will be set to the selected subchannel, or nullptr on failure or when
+    /// the LB policy decides to drop the call.
+    RefCountedPtr<ConnectedSubchannel> connected_subchannel;
+    /// Callback set by lb policy to be notified of trailing metadata.
+    /// The callback must be scheduled on grpc_schedule_on_exec_ctx.
+    // TODO(roth): Provide a cleaner callback API.
+    grpc_closure* recv_trailing_metadata_ready = nullptr;
+    /// The address that will be set to point to the original
+    /// recv_trailing_metadata_ready callback, to be invoked by the LB
+    /// policy's recv_trailing_metadata_ready callback when complete.
+    /// Must be non-null if recv_trailing_metadata_ready is non-null.
+    // TODO(roth): Consider making the recv_trailing_metadata closure a
+    // synchronous callback, in which case it is not responsible for
+    // chaining to the next callback, so this can be removed from the API.
+    grpc_closure** original_recv_trailing_metadata_ready = nullptr;
+    /// If this is not nullptr, then the client channel will point it to the
+    /// call's trailing metadata before invoking recv_trailing_metadata_ready.
+    /// If this is nullptr, then the callback will still be called.
+    /// The lb does not have ownership of the metadata.
+    // TODO(roth): If we make this a synchronous callback, then this can
+    // be passed to the callback as a parameter and can be removed from
+    // the API here.
+    grpc_metadata_batch** recv_trailing_metadata = nullptr;
+  };
+
+  /// The result of picking a subchannel for an RPC.
+  enum PickResult {
+    // Pick complete.  If connected_subchannel is non-null, client channel
+    // can immediately proceed with the call on connected_subchannel;
+    // otherwise, call should be dropped.
+    PICK_COMPLETE,
+    // Pick cannot be completed until something changes on the control
+    // plane.  Client channel will queue the pick and try again the
+    // next time the picker is updated.
+    PICK_QUEUE,
+    // LB policy is in transient failure.  If the pick is wait_for_ready,
+    // client channel will wait for the next picker and try again;
+    // otherwise, the call will be failed immediately (although it may
+    // be retried if the client channel is configured to do so).
+    // The Pick() method will set its error parameter if this value is
+    // returned.
+    PICK_TRANSIENT_FAILURE,
+  };
+
+  /// A subchannel picker is the object used to pick the subchannel to
+  /// use for a given RPC.
+  ///
+  /// Pickers are intended to encapsulate all of the state and logic
+  /// needed on the data plane (i.e., to actually process picks for
+  /// individual RPCs sent on the channel) while excluding all of the
+  /// state and logic needed on the control plane (i.e., resolver
+  /// updates, connectivity state notifications, etc); the latter should
+  /// live in the LB policy object itself.
+  ///
+  /// Currently, pickers are always accessed from within the
+  /// client_channel combiner, so they do not have to be thread-safe.
+  // TODO(roth): In a subsequent PR, split the data plane work (i.e.,
+  // the interaction with the picker) and the control plane work (i.e.,
+  // the interaction with the LB policy) into two different
+  // synchronization mechanisms, to avoid lock contention between the two.
+  class SubchannelPicker {
+   public:
+    SubchannelPicker() = default;
+    virtual ~SubchannelPicker() = default;
+
+    virtual PickResult Pick(PickArgs* pick, grpc_error** error) GRPC_ABSTRACT;
+
+    GRPC_ABSTRACT_BASE_CLASS
+  };
+
+  /// A proxy object used by the LB policy to communicate with the client
+  /// channel.
+  class ChannelControlHelper {
+   public:
+    ChannelControlHelper() = default;
+    virtual ~ChannelControlHelper() = default;
+
+    /// Creates a new subchannel with the specified channel args.
+    virtual Subchannel* CreateSubchannel(const grpc_channel_args& args)
+        GRPC_ABSTRACT;
+
+    /// Creates a channel with the specified target and channel args.
+    /// This can be used in cases where the LB policy needs to create a
+    /// channel for its own use (e.g., to talk to an external load balancer).
+    virtual grpc_channel* CreateChannel(
+        const char* target, const grpc_channel_args& args) GRPC_ABSTRACT;
+
+    /// Sets the connectivity state and returns a new picker to be used
+    /// by the client channel.
+    virtual void UpdateState(grpc_connectivity_state state,
+                             grpc_error* state_error,
+                             UniquePtr<SubchannelPicker>) GRPC_ABSTRACT;
+
+    /// Requests that the resolver re-resolve.
+    virtual void RequestReresolution() GRPC_ABSTRACT;
+
+    GRPC_ABSTRACT_BASE_CLASS
+  };
+
+  /// Configuration for an LB policy instance.
+  // TODO(roth): Find a better JSON representation for this API.
+  class Config : public RefCounted<Config> {
+   public:
+    Config(const grpc_json* lb_config,
+           RefCountedPtr<ServiceConfig> service_config)
+        : json_(lb_config), service_config_(std::move(service_config)) {}
+
+    const char* name() const { return json_->key; }
+    const grpc_json* config() const { return json_->child; }
+    RefCountedPtr<ServiceConfig> service_config() const {
+      return service_config_;
+    }
+
+   private:
+    const grpc_json* json_;
+    RefCountedPtr<ServiceConfig> service_config_;
+  };
+
+  /// Data passed to the UpdateLocked() method when new addresses and
+  /// config are available.
+  struct UpdateArgs {
+    ServerAddressList addresses;
+    RefCountedPtr<Config> config;
+    const grpc_channel_args* args = nullptr;
+
+    // TODO(roth): Remove everything below once channel args is
+    // converted to a copyable and movable C++ object.
+    UpdateArgs() = default;
+    ~UpdateArgs() { grpc_channel_args_destroy(args); }
+    UpdateArgs(const UpdateArgs& other);
+    UpdateArgs(UpdateArgs&& other);
+    UpdateArgs& operator=(const UpdateArgs& other);
+    UpdateArgs& operator=(UpdateArgs&& other);
+  };
+
+  /// 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.
@@ -52,53 +238,17 @@ class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
     // API should change to take a smart pointer that does pass ownership
     // of a reference.
     grpc_combiner* combiner = nullptr;
-    /// Used to create channels and subchannels.
-    grpc_client_channel_factory* client_channel_factory = nullptr;
-    /// Subchannel pool.
-    RefCountedPtr<SubchannelPoolInterface> subchannel_pool;
-    /// Channel args from the resolver.
-    /// Note that the LB policy gets the set of addresses from the
-    /// GRPC_ARG_SERVER_ADDRESS_LIST channel arg.
-    grpc_channel_args* args = nullptr;
-    /// Load balancing config from the resolver.
-    grpc_json* lb_config = nullptr;
+    /// Channel control helper.
+    /// Note: LB policies MUST NOT call any method on the helper from
+    /// their constructor.
+    UniquePtr<ChannelControlHelper> channel_control_helper;
+    /// Channel args.
+    // TODO(roth): Find a better channel args representation for this API.
+    const grpc_channel_args* args = nullptr;
   };
 
-  /// State used for an LB pick.
-  struct PickState {
-    /// Initial metadata associated with the picking call.
-    grpc_metadata_batch* initial_metadata = nullptr;
-    /// Pointer to bitmask used for selective cancelling. See
-    /// \a CancelMatchingPicksLocked() and \a GRPC_INITIAL_METADATA_* in
-    /// grpc_types.h.
-    uint32_t* initial_metadata_flags = nullptr;
-    /// Storage for LB token in \a initial_metadata, or nullptr if not used.
-    grpc_linked_mdelem lb_token_mdelem_storage;
-    /// Closure to run when pick is complete, if not completed synchronously.
-    /// If null, pick will fail if a result is not available synchronously.
-    grpc_closure* on_complete = nullptr;
-    // Callback set by lb policy to be notified of trailing metadata.
-    // The callback must be scheduled on grpc_schedule_on_exec_ctx.
-    grpc_closure* recv_trailing_metadata_ready = nullptr;
-    // The address that will be set to point to the original
-    // recv_trailing_metadata_ready callback, to be invoked by the LB
-    // policy's recv_trailing_metadata_ready callback when complete.
-    // Must be non-null if recv_trailing_metadata_ready is non-null.
-    grpc_closure** original_recv_trailing_metadata_ready = nullptr;
-    // If this is not nullptr, then the client channel will point it to the
-    // call's trailing metadata before invoking recv_trailing_metadata_ready.
-    // If this is nullptr, then the callback will still be called.
-    // The lb does not have ownership of the metadata.
-    grpc_metadata_batch** recv_trailing_metadata = nullptr;
-    /// Will be set to the selected subchannel, or nullptr on failure or when
-    /// the LB policy decides to drop the call.
-    RefCountedPtr<ConnectedSubchannel> connected_subchannel;
-    /// Will be populated with context to pass to the subchannel call, if
-    /// needed.
-    grpc_call_context_element subchannel_call_context[GRPC_CONTEXT_COUNT] = {};
-    /// Next pointer.  For internal use by LB policy.
-    PickState* next = nullptr;
-  };
+  explicit LoadBalancingPolicy(Args args, intptr_t initial_refcount = 1);
+  virtual ~LoadBalancingPolicy();
 
   // Not copyable nor movable.
   LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
@@ -107,135 +257,103 @@ class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
   /// Returns the name of the LB policy.
   virtual const char* name() const GRPC_ABSTRACT;
 
-  /// Updates the policy with a new set of \a args and a new \a lb_config from
-  /// the resolver. Note that the LB policy gets the set of addresses from the
-  /// GRPC_ARG_SERVER_ADDRESS_LIST channel arg.
-  virtual void UpdateLocked(const grpc_channel_args& args,
-                            grpc_json* lb_config) GRPC_ABSTRACT;
-
-  /// Finds an appropriate subchannel for a call, based on data in \a pick.
-  /// \a pick must remain alive until the pick is complete.
-  ///
-  /// If a result is known immediately, returns true, setting \a *error
-  /// upon failure.  Otherwise, \a pick->on_complete will be invoked once
-  /// the pick is complete with its error argument set to indicate success
-  /// or failure.
-  ///
-  /// If \a pick->on_complete is null and no result is known immediately,
-  /// a synchronous failure will be returned (i.e., \a *error will be
-  /// set and true will be returned).
-  virtual bool PickLocked(PickState* pick, grpc_error** error) GRPC_ABSTRACT;
-
-  /// Cancels \a pick.
-  /// The \a on_complete callback of the pending pick will be invoked with
-  /// \a pick->connected_subchannel set to null.
-  virtual void CancelPickLocked(PickState* pick,
-                                grpc_error* error) GRPC_ABSTRACT;
-
-  /// Cancels all pending picks for which their \a initial_metadata_flags (as
-  /// given in the call to \a PickLocked()) matches
-  /// \a initial_metadata_flags_eq when ANDed with
-  /// \a initial_metadata_flags_mask.
-  virtual void CancelMatchingPicksLocked(uint32_t initial_metadata_flags_mask,
-                                         uint32_t initial_metadata_flags_eq,
-                                         grpc_error* error) GRPC_ABSTRACT;
-
-  /// Requests a notification when the connectivity state of the policy
-  /// changes from \a *state.  When that happens, sets \a *state to the
-  /// new state and schedules \a closure.
-  virtual void NotifyOnStateChangeLocked(grpc_connectivity_state* state,
-                                         grpc_closure* closure) GRPC_ABSTRACT;
-
-  /// Returns the policy's current connectivity state.  Sets \a error to
-  /// the associated error, if any.
-  virtual grpc_connectivity_state CheckConnectivityLocked(
-      grpc_error** connectivity_error) GRPC_ABSTRACT;
-
-  /// Hands off pending picks to \a new_policy.
-  virtual void HandOffPendingPicksLocked(LoadBalancingPolicy* new_policy)
-      GRPC_ABSTRACT;
+  /// Updates the policy with new data from the resolver.  Will be invoked
+  /// immediately after LB policy is constructed, and then again whenever
+  /// the resolver returns a new result.
+  virtual void UpdateLocked(UpdateArgs) GRPC_ABSTRACT;  // NOLINT
 
   /// Tries to enter a READY connectivity state.
-  /// TODO(roth): As part of restructuring how we handle IDLE state,
-  /// consider whether this method is still needed.
-  virtual void ExitIdleLocked() GRPC_ABSTRACT;
+  /// This is a no-op by default, since most LB policies never go into
+  /// IDLE state.
+  virtual void ExitIdleLocked() {}
 
   /// Resets connection backoff.
   virtual void ResetBackoffLocked() GRPC_ABSTRACT;
 
   /// Populates child_subchannels and child_channels with the uuids of this
-  /// LB policy's referenced children. This is not invoked from the
-  /// client_channel's combiner. The implementation is responsible for
-  /// providing its own synchronization.
+  /// LB policy's referenced children.
+  ///
+  /// This is not invoked from the client_channel's combiner. The
+  /// implementation is responsible for providing its own synchronization.
   virtual void FillChildRefsForChannelz(
       channelz::ChildRefsList* child_subchannels,
       channelz::ChildRefsList* child_channels) GRPC_ABSTRACT;
 
-  void Orphan() override {
-    // Invoke ShutdownAndUnrefLocked() inside of the combiner.
-    GRPC_CLOSURE_SCHED(
-        GRPC_CLOSURE_CREATE(&LoadBalancingPolicy::ShutdownAndUnrefLocked, this,
-                            grpc_combiner_scheduler(combiner_)),
-        GRPC_ERROR_NONE);
+  void set_channelz_node(
+      RefCountedPtr<channelz::ClientChannelNode> channelz_node) {
+    channelz_node_ = std::move(channelz_node);
   }
 
+  grpc_pollset_set* interested_parties() const { return interested_parties_; }
+
+  void Orphan() override;
+
   /// Returns the JSON node of policy (with both policy name and config content)
   /// given the JSON node of a LoadBalancingConfig array.
   static grpc_json* ParseLoadBalancingConfig(const grpc_json* lb_config_array);
 
-  /// Sets the re-resolution closure to \a request_reresolution.
-  void SetReresolutionClosureLocked(grpc_closure* request_reresolution) {
-    GPR_ASSERT(request_reresolution_ == nullptr);
-    request_reresolution_ = request_reresolution;
-  }
+  // A picker that returns PICK_QUEUE for all picks.
+  // Also calls the parent LB policy's ExitIdleLocked() method when the
+  // first pick is seen.
+  class QueuePicker : public SubchannelPicker {
+   public:
+    explicit QueuePicker(RefCountedPtr<LoadBalancingPolicy> parent)
+        : parent_(std::move(parent)) {}
 
-  grpc_pollset_set* interested_parties() const { return interested_parties_; }
+    PickResult Pick(PickArgs* pick, grpc_error** error) override;
 
-  // Callers that need their own reference can call the returned
-  // object's Ref() method.
-  SubchannelPoolInterface* subchannel_pool() const {
-    return subchannel_pool_.get();
-  }
+   private:
+    static void CallExitIdle(void* arg, grpc_error* error);
+
+    RefCountedPtr<LoadBalancingPolicy> parent_;
+    bool exit_idle_called_ = false;
+  };
+
+  // A picker that returns PICK_TRANSIENT_FAILURE for all picks.
+  class TransientFailurePicker : public SubchannelPicker {
+   public:
+    explicit TransientFailurePicker(grpc_error* error) : error_(error) {}
+    ~TransientFailurePicker() override { GRPC_ERROR_UNREF(error_); }
+
+    PickResult Pick(PickArgs* pick, grpc_error** error) override {
+      *error = GRPC_ERROR_REF(error_);
+      return PICK_TRANSIENT_FAILURE;
+    }
+
+   private:
+    grpc_error* error_;
+  };
 
   GRPC_ABSTRACT_BASE_CLASS
 
  protected:
-  GPRC_ALLOW_CLASS_TO_USE_NON_PUBLIC_DELETE
+  grpc_combiner* combiner() const { return combiner_; }
 
-  explicit LoadBalancingPolicy(Args args);
-  virtual ~LoadBalancingPolicy();
+  // Note: LB policies MUST NOT call any method on the helper from their
+  // constructor.
+  // Note: This will return null after ShutdownLocked() has been called.
+  ChannelControlHelper* channel_control_helper() const {
+    return channel_control_helper_.get();
+  }
 
-  grpc_combiner* combiner() const { return combiner_; }
-  grpc_client_channel_factory* client_channel_factory() const {
-    return client_channel_factory_;
+  channelz::ClientChannelNode* channelz_node() const {
+    return channelz_node_.get();
   }
 
-  /// Shuts down the policy.  Any pending picks that have not been
-  /// handed off to a new policy via HandOffPendingPicksLocked() will be
-  /// failed.
+  /// Shuts down the policy.
   virtual void ShutdownLocked() GRPC_ABSTRACT;
 
-  /// Tries to request a re-resolution.
-  void TryReresolutionLocked(grpc_core::TraceFlag* grpc_lb_trace,
-                             grpc_error* error);
-
  private:
-  static void ShutdownAndUnrefLocked(void* arg, grpc_error* ignored) {
-    LoadBalancingPolicy* policy = static_cast<LoadBalancingPolicy*>(arg);
-    policy->ShutdownLocked();
-    policy->Unref();
-  }
+  static void ShutdownAndUnrefLocked(void* arg, grpc_error* ignored);
 
   /// Combiner under which LB policy actions take place.
   grpc_combiner* combiner_;
-  /// Client channel factory, used to create channels and subchannels.
-  grpc_client_channel_factory* client_channel_factory_;
-  /// Subchannel pool.
-  RefCountedPtr<SubchannelPoolInterface> subchannel_pool_;
   /// Owned pointer to interested parties in load balancing decisions.
   grpc_pollset_set* interested_parties_;
-  /// Callback to force a re-resolution.
-  grpc_closure* request_reresolution_;
+  /// Channel control helper.
+  UniquePtr<ChannelControlHelper> channel_control_helper_;
+  /// Channelz node.
+  RefCountedPtr<channelz::ClientChannelNode> channelz_node_;
 };
 
 }  // namespace grpc_core