grpc-flamingo 1.11.0

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

@@ -0,0 +1,253 @@
+/*
+ *
+ * Copyright 2015 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 <string.h>
+
+#include <grpc/support/alloc.h>
+
+#include "src/core/ext/filters/client_channel/lb_policy/subchannel_list.h"
+#include "src/core/lib/channel/channel_args.h"
+#include "src/core/lib/debug/trace.h"
+#include "src/core/lib/iomgr/closure.h"
+#include "src/core/lib/iomgr/combiner.h"
+#include "src/core/lib/iomgr/sockaddr_utils.h"
+#include "src/core/lib/transport/connectivity_state.h"
+
+void grpc_lb_subchannel_data_unref_subchannel(grpc_lb_subchannel_data* sd,
+                                              const char* reason) {
+  if (sd->subchannel != nullptr) {
+    if (sd->subchannel_list->tracer->enabled()) {
+      gpr_log(GPR_DEBUG,
+              "[%s %p] subchannel list %p index %" PRIuPTR " of %" PRIuPTR
+              " (subchannel %p): unreffing subchannel",
+              sd->subchannel_list->tracer->name(), sd->subchannel_list->policy,
+              sd->subchannel_list,
+              static_cast<size_t>(sd - sd->subchannel_list->subchannels),
+              sd->subchannel_list->num_subchannels, sd->subchannel);
+    }
+    GRPC_SUBCHANNEL_UNREF(sd->subchannel, reason);
+    sd->subchannel = nullptr;
+    sd->connected_subchannel.reset();
+    if (sd->user_data != nullptr) {
+      GPR_ASSERT(sd->user_data_vtable != nullptr);
+      sd->user_data_vtable->destroy(sd->user_data);
+      sd->user_data = nullptr;
+    }
+  }
+}
+
+void grpc_lb_subchannel_data_start_connectivity_watch(
+    grpc_lb_subchannel_data* sd) {
+  if (sd->subchannel_list->tracer->enabled()) {
+    gpr_log(
+        GPR_DEBUG,
+        "[%s %p] subchannel list %p index %" PRIuPTR " of %" PRIuPTR
+        " (subchannel %p): requesting connectivity change "
+        "notification (from %s)",
+        sd->subchannel_list->tracer->name(), sd->subchannel_list->policy,
+        sd->subchannel_list,
+        static_cast<size_t>(sd - sd->subchannel_list->subchannels),
+        sd->subchannel_list->num_subchannels, sd->subchannel,
+        grpc_connectivity_state_name(sd->pending_connectivity_state_unsafe));
+  }
+  sd->connectivity_notification_pending = true;
+  grpc_subchannel_notify_on_state_change(
+      sd->subchannel, sd->subchannel_list->policy->interested_parties(),
+      &sd->pending_connectivity_state_unsafe,
+      &sd->connectivity_changed_closure);
+}
+
+void grpc_lb_subchannel_data_stop_connectivity_watch(
+    grpc_lb_subchannel_data* sd) {
+  if (sd->subchannel_list->tracer->enabled()) {
+    gpr_log(GPR_DEBUG,
+            "[%s %p] subchannel list %p index %" PRIuPTR " of %" PRIuPTR
+            " (subchannel %p): stopping connectivity watch",
+            sd->subchannel_list->tracer->name(), sd->subchannel_list->policy,
+            sd->subchannel_list,
+            static_cast<size_t>(sd - sd->subchannel_list->subchannels),
+            sd->subchannel_list->num_subchannels, sd->subchannel);
+  }
+  GPR_ASSERT(sd->connectivity_notification_pending);
+  sd->connectivity_notification_pending = false;
+}
+
+grpc_lb_subchannel_list* grpc_lb_subchannel_list_create(
+    grpc_core::LoadBalancingPolicy* p, grpc_core::TraceFlag* tracer,
+    const grpc_lb_addresses* addresses, grpc_combiner* combiner,
+    grpc_client_channel_factory* client_channel_factory,
+    const grpc_channel_args& args, grpc_iomgr_cb_func connectivity_changed_cb) {
+  grpc_lb_subchannel_list* subchannel_list =
+      static_cast<grpc_lb_subchannel_list*>(
+          gpr_zalloc(sizeof(*subchannel_list)));
+  if (tracer->enabled()) {
+    gpr_log(GPR_DEBUG,
+            "[%s %p] Creating subchannel list %p for %" PRIuPTR " subchannels",
+            tracer->name(), p, subchannel_list, addresses->num_addresses);
+  }
+  subchannel_list->policy = p;
+  subchannel_list->tracer = tracer;
+  gpr_ref_init(&subchannel_list->refcount, 1);
+  subchannel_list->subchannels = static_cast<grpc_lb_subchannel_data*>(
+      gpr_zalloc(sizeof(grpc_lb_subchannel_data) * addresses->num_addresses));
+  // We need to remove the LB addresses in order to be able to compare the
+  // subchannel keys of subchannels from a different batch of addresses.
+  static const char* keys_to_remove[] = {GRPC_ARG_SUBCHANNEL_ADDRESS,
+                                         GRPC_ARG_LB_ADDRESSES};
+  // Create a subchannel for each address.
+  grpc_subchannel_args sc_args;
+  size_t subchannel_index = 0;
+  for (size_t i = 0; i < addresses->num_addresses; i++) {
+    // If there were any balancer, we would have chosen grpclb policy instead.
+    GPR_ASSERT(!addresses->addresses[i].is_balancer);
+    memset(&sc_args, 0, sizeof(grpc_subchannel_args));
+    grpc_arg addr_arg =
+        grpc_create_subchannel_address_arg(&addresses->addresses[i].address);
+    grpc_channel_args* new_args = grpc_channel_args_copy_and_add_and_remove(
+        &args, keys_to_remove, GPR_ARRAY_SIZE(keys_to_remove), &addr_arg, 1);
+    gpr_free(addr_arg.value.string);
+    sc_args.args = new_args;
+    grpc_subchannel* subchannel = grpc_client_channel_factory_create_subchannel(
+        client_channel_factory, &sc_args);
+    grpc_channel_args_destroy(new_args);
+    if (subchannel == nullptr) {
+      // Subchannel could not be created.
+      if (tracer->enabled()) {
+        char* address_uri =
+            grpc_sockaddr_to_uri(&addresses->addresses[i].address);
+        gpr_log(GPR_DEBUG,
+                "[%s %p] could not create subchannel for address uri %s, "
+                "ignoring",
+                tracer->name(), subchannel_list->policy, address_uri);
+        gpr_free(address_uri);
+      }
+      continue;
+    }
+    if (tracer->enabled()) {
+      char* address_uri =
+          grpc_sockaddr_to_uri(&addresses->addresses[i].address);
+      gpr_log(GPR_DEBUG,
+              "[%s %p] subchannel list %p index %" PRIuPTR
+              ": Created subchannel %p for address uri %s",
+              tracer->name(), p, subchannel_list, subchannel_index, subchannel,
+              address_uri);
+      gpr_free(address_uri);
+    }
+    grpc_lb_subchannel_data* sd =
+        &subchannel_list->subchannels[subchannel_index++];
+    sd->subchannel_list = subchannel_list;
+    sd->subchannel = subchannel;
+    GRPC_CLOSURE_INIT(&sd->connectivity_changed_closure,
+                      connectivity_changed_cb, sd,
+                      grpc_combiner_scheduler(combiner));
+    // We assume that the current state is IDLE.  If not, we'll get a
+    // callback telling us that.
+    sd->prev_connectivity_state = GRPC_CHANNEL_IDLE;
+    sd->curr_connectivity_state = GRPC_CHANNEL_IDLE;
+    sd->pending_connectivity_state_unsafe = GRPC_CHANNEL_IDLE;
+    sd->user_data_vtable = addresses->user_data_vtable;
+    if (sd->user_data_vtable != nullptr) {
+      sd->user_data =
+          sd->user_data_vtable->copy(addresses->addresses[i].user_data);
+    }
+  }
+  subchannel_list->num_subchannels = subchannel_index;
+  subchannel_list->num_idle = subchannel_index;
+  return subchannel_list;
+}
+
+static void subchannel_list_destroy(grpc_lb_subchannel_list* subchannel_list) {
+  if (subchannel_list->tracer->enabled()) {
+    gpr_log(GPR_DEBUG, "[%s %p] Destroying subchannel_list %p",
+            subchannel_list->tracer->name(), subchannel_list->policy,
+            subchannel_list);
+  }
+  for (size_t i = 0; i < subchannel_list->num_subchannels; i++) {
+    grpc_lb_subchannel_data* sd = &subchannel_list->subchannels[i];
+    grpc_lb_subchannel_data_unref_subchannel(sd, "subchannel_list_destroy");
+  }
+  gpr_free(subchannel_list->subchannels);
+  gpr_free(subchannel_list);
+}
+
+void grpc_lb_subchannel_list_ref(grpc_lb_subchannel_list* subchannel_list,
+                                 const char* reason) {
+  gpr_ref_non_zero(&subchannel_list->refcount);
+  if (subchannel_list->tracer->enabled()) {
+    const gpr_atm count = gpr_atm_acq_load(&subchannel_list->refcount.count);
+    gpr_log(GPR_DEBUG, "[%s %p] subchannel_list %p REF %lu->%lu (%s)",
+            subchannel_list->tracer->name(), subchannel_list->policy,
+            subchannel_list, static_cast<unsigned long>(count - 1),
+            static_cast<unsigned long>(count), reason);
+  }
+}
+
+void grpc_lb_subchannel_list_unref(grpc_lb_subchannel_list* subchannel_list,
+                                   const char* reason) {
+  const bool done = gpr_unref(&subchannel_list->refcount);
+  if (subchannel_list->tracer->enabled()) {
+    const gpr_atm count = gpr_atm_acq_load(&subchannel_list->refcount.count);
+    gpr_log(GPR_DEBUG, "[%s %p] subchannel_list %p UNREF %lu->%lu (%s)",
+            subchannel_list->tracer->name(), subchannel_list->policy,
+            subchannel_list, static_cast<unsigned long>(count + 1),
+            static_cast<unsigned long>(count), reason);
+  }
+  if (done) {
+    subchannel_list_destroy(subchannel_list);
+  }
+}
+
+static void subchannel_data_cancel_connectivity_watch(
+    grpc_lb_subchannel_data* sd, const char* reason) {
+  if (sd->subchannel_list->tracer->enabled()) {
+    gpr_log(GPR_DEBUG,
+            "[%s %p] subchannel list %p index %" PRIuPTR " of %" PRIuPTR
+            " (subchannel %p): canceling connectivity watch (%s)",
+            sd->subchannel_list->tracer->name(), sd->subchannel_list->policy,
+            sd->subchannel_list,
+            static_cast<size_t>(sd - sd->subchannel_list->subchannels),
+            sd->subchannel_list->num_subchannels, sd->subchannel, reason);
+  }
+  grpc_subchannel_notify_on_state_change(sd->subchannel, nullptr, nullptr,
+                                         &sd->connectivity_changed_closure);
+}
+
+void grpc_lb_subchannel_list_shutdown_and_unref(
+    grpc_lb_subchannel_list* subchannel_list, const char* reason) {
+  if (subchannel_list->tracer->enabled()) {
+    gpr_log(GPR_DEBUG, "[%s %p] Shutting down subchannel_list %p (%s)",
+            subchannel_list->tracer->name(), subchannel_list->policy,
+            subchannel_list, reason);
+  }
+  GPR_ASSERT(!subchannel_list->shutting_down);
+  subchannel_list->shutting_down = true;
+  for (size_t i = 0; i < subchannel_list->num_subchannels; i++) {
+    grpc_lb_subchannel_data* sd = &subchannel_list->subchannels[i];
+    // If there's a pending notification for this subchannel, cancel it;
+    // the callback is responsible for unreffing the subchannel.
+    // Otherwise, unref the subchannel directly.
+    if (sd->connectivity_notification_pending) {
+      subchannel_data_cancel_connectivity_watch(sd, reason);
+    } else if (sd->subchannel != nullptr) {
+      grpc_lb_subchannel_data_unref_subchannel(sd, reason);
+    }
+  }
+  grpc_lb_subchannel_list_unref(subchannel_list, reason);
+}

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

@@ -0,0 +1,136 @@
+/*
+ *
+ * Copyright 2015 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_SUBCHANNEL_LIST_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_SUBCHANNEL_LIST_H
+
+#include <grpc/support/port_platform.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/debug/trace.h"
+#include "src/core/lib/gprpp/ref_counted_ptr.h"
+#include "src/core/lib/transport/connectivity_state.h"
+
+// TODO(roth): This code is intended to be shared between pick_first and
+// round_robin.  However, the interface needs more work to provide clean
+// encapsulation.  For example, the structs here have some fields that are
+// only used in one of the two (e.g., the state counters in
+// grpc_lb_subchannel_list and the prev_connectivity_state field in
+// grpc_lb_subchannel_data are only used in round_robin, and the
+// checking_subchannel field in grpc_lb_subchannel_list is only used by
+// pick_first).  Also, there is probably some code duplication between the
+// connectivity state notification callback code in both pick_first and
+// round_robin that could be refactored and moved here.  In a future PR,
+// need to clean this up.
+
+typedef struct grpc_lb_subchannel_list grpc_lb_subchannel_list;
+
+typedef struct {
+  /** backpointer to owning subchannel list */
+  grpc_lb_subchannel_list* subchannel_list;
+  /** subchannel itself */
+  grpc_subchannel* subchannel;
+  grpc_core::RefCountedPtr<grpc_core::ConnectedSubchannel> connected_subchannel;
+  /** Is a connectivity notification pending? */
+  bool connectivity_notification_pending;
+  /** notification that connectivity has changed on subchannel */
+  grpc_closure connectivity_changed_closure;
+  /** previous and current connectivity states.  Updated by \a
+   * \a connectivity_changed_closure based on
+   * \a pending_connectivity_state_unsafe. */
+  grpc_connectivity_state prev_connectivity_state;
+  grpc_connectivity_state curr_connectivity_state;
+  /** connectivity state to be updated by
+   * grpc_subchannel_notify_on_state_change(), not guarded by
+   * the combiner.  To be copied to \a curr_connectivity_state by
+   * \a connectivity_changed_closure. */
+  grpc_connectivity_state pending_connectivity_state_unsafe;
+  /** the subchannel's target user data */
+  void* user_data;
+  /** vtable to operate over \a user_data */
+  const grpc_lb_user_data_vtable* user_data_vtable;
+} grpc_lb_subchannel_data;
+
+/// Unrefs the subchannel contained in sd.
+void grpc_lb_subchannel_data_unref_subchannel(grpc_lb_subchannel_data* sd,
+                                              const char* reason);
+
+/// Starts watching the connectivity state of the subchannel.
+/// The connectivity_changed_cb callback must invoke either
+/// grpc_lb_subchannel_data_stop_connectivity_watch() or again call
+/// grpc_lb_subchannel_data_start_connectivity_watch().
+void grpc_lb_subchannel_data_start_connectivity_watch(
+    grpc_lb_subchannel_data* sd);
+
+/// Stops watching the connectivity state of the subchannel.
+void grpc_lb_subchannel_data_stop_connectivity_watch(
+    grpc_lb_subchannel_data* sd);
+
+struct grpc_lb_subchannel_list {
+  /** backpointer to owning policy */
+  grpc_core::LoadBalancingPolicy* policy;
+
+  grpc_core::TraceFlag* tracer;
+
+  /** all our subchannels */
+  size_t num_subchannels;
+  grpc_lb_subchannel_data* subchannels;
+
+  /** Index into subchannels of the one we're currently checking.
+   * Used when connecting to subchannels serially instead of in parallel. */
+  // TODO(roth): When we have time, we can probably make this go away
+  // and compute the index dynamically by subtracting
+  // subchannel_list->subchannels from the subchannel_data pointer.
+  size_t checking_subchannel;
+
+  /** how many subchannels are in state READY */
+  size_t num_ready;
+  /** how many subchannels are in state TRANSIENT_FAILURE */
+  size_t num_transient_failures;
+  /** how many subchannels are in state IDLE */
+  size_t num_idle;
+
+  /** There will be one ref for each entry in subchannels for which there is a
+   * pending connectivity state watcher callback. */
+  gpr_refcount refcount;
+
+  /** Is this list shutting down? This may be true due to the shutdown of the
+   * policy itself or because a newer update has arrived while this one hadn't
+   * finished processing. */
+  bool shutting_down;
+};
+
+grpc_lb_subchannel_list* grpc_lb_subchannel_list_create(
+    grpc_core::LoadBalancingPolicy* p, grpc_core::TraceFlag* tracer,
+    const grpc_lb_addresses* addresses, grpc_combiner* combiner,
+    grpc_client_channel_factory* client_channel_factory,
+    const grpc_channel_args& args, grpc_iomgr_cb_func connectivity_changed_cb);
+
+void grpc_lb_subchannel_list_ref(grpc_lb_subchannel_list* subchannel_list,
+                                 const char* reason);
+
+void grpc_lb_subchannel_list_unref(grpc_lb_subchannel_list* subchannel_list,
+                                   const char* reason);
+
+/// Mark subchannel_list as discarded. Unsubscribes all its subchannels. The
+/// connectivity state notification callback will ultimately unref it.
+void grpc_lb_subchannel_list_shutdown_and_unref(
+    grpc_lb_subchannel_list* subchannel_list, const char* reason);
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_SUBCHANNEL_LIST_H */

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

@@ -0,0 +1,59 @@
+/*
+ *
+ * Copyright 2015 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.h"
+#include "src/core/lib/iomgr/combiner.h"
+
+grpc_core::DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(
+    false, "lb_policy_refcount");
+
+namespace grpc_core {
+
+LoadBalancingPolicy::LoadBalancingPolicy(const Args& args)
+    : InternallyRefCountedWithTracing(&grpc_trace_lb_policy_refcount),
+      combiner_(GRPC_COMBINER_REF(args.combiner, "lb_policy")),
+      client_channel_factory_(args.client_channel_factory),
+      interested_parties_(grpc_pollset_set_create()),
+      request_reresolution_(nullptr) {}
+
+LoadBalancingPolicy::~LoadBalancingPolicy() {
+  grpc_pollset_set_destroy(interested_parties_);
+  GRPC_COMBINER_UNREF(combiner_, "lb_policy");
+}
+
+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_DEBUG,
+              "%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_DEBUG, "%s %p: no available re-resolution closure.",
+              grpc_lb_trace->name(), this);
+    }
+  }
+}
+
+}  // namespace grpc_core

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

@@ -0,0 +1,201 @@
+/*
+ *
+ * Copyright 2015 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_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/ext/filters/client_channel/client_channel_factory.h"
+#include "src/core/ext/filters/client_channel/subchannel.h"
+#include "src/core/lib/gprpp/abstract.h"
+#include "src/core/lib/gprpp/orphanable.h"
+#include "src/core/lib/gprpp/ref_counted_ptr.h"
+#include "src/core/lib/iomgr/combiner.h"
+#include "src/core/lib/iomgr/polling_entity.h"
+#include "src/core/lib/transport/connectivity_state.h"
+
+extern grpc_core::DebugOnlyTraceFlag grpc_trace_lb_policy_refcount;
+
+namespace grpc_core {
+
+/// Interface for load balancing policies.
+///
+/// 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().
+class LoadBalancingPolicy
+    : public InternallyRefCountedWithTracing<LoadBalancingPolicy> {
+ public:
+  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.
+    grpc_combiner* combiner = nullptr;
+    /// Used to create channels and subchannels.
+    grpc_client_channel_factory* client_channel_factory = nullptr;
+    /// Channel args from the resolver.
+    /// Note that the LB policy gets the set of addresses from the
+    /// GRPC_ARG_LB_ADDRESSES channel arg.
+    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;
+    /// Bitmask used for selective cancelling. See
+    /// \a CancelMatchingPicksLocked() and \a GRPC_INITIAL_METADATA_* in
+    /// grpc_types.h.
+    uint32_t initial_metadata_flags;
+    /// 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.
+    grpc_closure* on_complete;
+    /// 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];
+    /// Upon success, \a *user_data will be set to whatever opaque information
+    /// may need to be propagated from the LB policy, or nullptr if not needed.
+    // TODO(roth): As part of revamping our metadata APIs, try to find a
+    // way to clean this up and C++-ify it.
+    void** user_data;
+    /// Next pointer.  For internal use by LB policy.
+    PickState* next;
+  };
+
+  // Not copyable nor movable.
+  LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
+  LoadBalancingPolicy& operator=(const LoadBalancingPolicy&) = delete;
+
+  /// Updates the policy with a new set of \a args from the resolver.
+  /// Note that the LB policy gets the set of addresses from the
+  /// GRPC_ARG_LB_ADDRESSES channel arg.
+  virtual void UpdateLocked(const grpc_channel_args& args) 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 the pick succeeds and a result is known immediately, returns true.
+  /// Otherwise, \a pick->on_complete will be invoked once the pick is
+  /// complete with its error argument set to indicate success or failure.
+  virtual bool PickLocked(PickState* pick) 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;
+
+  /// Performs a connected subchannel ping via \a ConnectedSubchannel::Ping()
+  /// against one of the connected subchannels managed by the policy.
+  /// Note: This is intended only for use in tests.
+  virtual void PingOneLocked(grpc_closure* on_initiate,
+                             grpc_closure* on_ack) GRPC_ABSTRACT;
+
+  /// 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;
+
+  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);
+  }
+
+  /// Sets the re-resolution closure to \a request_reresolution.
+  void SetReresolutionClosureLocked(grpc_closure* request_reresolution) {
+    GPR_ASSERT(request_reresolution_ == nullptr);
+    request_reresolution_ = request_reresolution;
+  }
+
+  grpc_pollset_set* interested_parties() const { return interested_parties_; }
+
+  GRPC_ABSTRACT_BASE_CLASS
+
+ protected:
+  explicit LoadBalancingPolicy(const Args& args);
+  virtual ~LoadBalancingPolicy();
+
+  grpc_combiner* combiner() const { return combiner_; }
+  grpc_client_channel_factory* client_channel_factory() const {
+    return client_channel_factory_;
+  }
+
+  /// Shuts down the policy.  Any pending picks that have not been
+  /// handed off to a new policy via HandOffPendingPicksLocked() will be
+  /// failed.
+  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();
+  }
+
+  /// 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_;
+  /// Owned pointer to interested parties in load balancing decisions.
+  grpc_pollset_set* interested_parties_;
+  /// Callback to force a re-resolution.
+  grpc_closure* request_reresolution_;
+};
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H */