grpc 1.18.0 → 1.22.0

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

@@ -23,72 +23,69 @@
 
 #include "src/core/ext/filters/client_channel/client_channel_channelz.h"
 #include "src/core/ext/filters/client_channel/connector.h"
+#include "src/core/ext/filters/client_channel/subchannel_interface.h"
+#include "src/core/ext/filters/client_channel/subchannel_pool_interface.h"
+#include "src/core/lib/backoff/backoff.h"
 #include "src/core/lib/channel/channel_stack.h"
-#include "src/core/lib/gpr/arena.h"
+#include "src/core/lib/gprpp/arena.h"
+#include "src/core/lib/gprpp/map.h"
 #include "src/core/lib/gprpp/ref_counted.h"
 #include "src/core/lib/gprpp/ref_counted_ptr.h"
+#include "src/core/lib/gprpp/sync.h"
 #include "src/core/lib/iomgr/polling_entity.h"
+#include "src/core/lib/iomgr/timer.h"
 #include "src/core/lib/transport/connectivity_state.h"
 #include "src/core/lib/transport/metadata.h"
 
 // Channel arg containing a grpc_resolved_address to connect to.
 #define GRPC_ARG_SUBCHANNEL_ADDRESS "grpc.subchannel_address"
 
-/** A (sub-)channel that knows how to connect to exactly one target
-    address. Provides a target for load balancing. */
-typedef struct grpc_subchannel grpc_subchannel;
-typedef struct grpc_subchannel_call grpc_subchannel_call;
-typedef struct grpc_subchannel_args grpc_subchannel_args;
-typedef struct grpc_subchannel_key grpc_subchannel_key;
-
+// For debugging refcounting.
 #ifndef NDEBUG
-#define GRPC_SUBCHANNEL_REF(p, r) \
-  grpc_subchannel_ref((p), __FILE__, __LINE__, (r))
+#define GRPC_SUBCHANNEL_REF(p, r) (p)->Ref(__FILE__, __LINE__, (r))
 #define GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(p, r) \
-  grpc_subchannel_ref_from_weak_ref((p), __FILE__, __LINE__, (r))
-#define GRPC_SUBCHANNEL_UNREF(p, r) \
-  grpc_subchannel_unref((p), __FILE__, __LINE__, (r))
-#define GRPC_SUBCHANNEL_WEAK_REF(p, r) \
-  grpc_subchannel_weak_ref((p), __FILE__, __LINE__, (r))
-#define GRPC_SUBCHANNEL_WEAK_UNREF(p, r) \
-  grpc_subchannel_weak_unref((p), __FILE__, __LINE__, (r))
-#define GRPC_SUBCHANNEL_CALL_REF(p, r) \
-  grpc_subchannel_call_ref((p), __FILE__, __LINE__, (r))
-#define GRPC_SUBCHANNEL_CALL_UNREF(p, r) \
-  grpc_subchannel_call_unref((p), __FILE__, __LINE__, (r))
+  (p)->RefFromWeakRef(__FILE__, __LINE__, (r))
+#define GRPC_SUBCHANNEL_UNREF(p, r) (p)->Unref(__FILE__, __LINE__, (r))
+#define GRPC_SUBCHANNEL_WEAK_REF(p, r) (p)->WeakRef(__FILE__, __LINE__, (r))
+#define GRPC_SUBCHANNEL_WEAK_UNREF(p, r) (p)->WeakUnref(__FILE__, __LINE__, (r))
 #define GRPC_SUBCHANNEL_REF_EXTRA_ARGS \
-  , const char *file, int line, const char *reason
+  const char *file, int line, const char *reason
+#define GRPC_SUBCHANNEL_REF_REASON reason
+#define GRPC_SUBCHANNEL_REF_MUTATE_EXTRA_ARGS \
+  , GRPC_SUBCHANNEL_REF_EXTRA_ARGS, const char* purpose
+#define GRPC_SUBCHANNEL_REF_MUTATE_PURPOSE(x) , file, line, reason, x
 #else
-#define GRPC_SUBCHANNEL_REF(p, r) grpc_subchannel_ref((p))
-#define GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(p, r) \
-  grpc_subchannel_ref_from_weak_ref((p))
-#define GRPC_SUBCHANNEL_UNREF(p, r) grpc_subchannel_unref((p))
-#define GRPC_SUBCHANNEL_WEAK_REF(p, r) grpc_subchannel_weak_ref((p))
-#define GRPC_SUBCHANNEL_WEAK_UNREF(p, r) grpc_subchannel_weak_unref((p))
-#define GRPC_SUBCHANNEL_CALL_REF(p, r) grpc_subchannel_call_ref((p))
-#define GRPC_SUBCHANNEL_CALL_UNREF(p, r) grpc_subchannel_call_unref((p))
+#define GRPC_SUBCHANNEL_REF(p, r) (p)->Ref()
+#define GRPC_SUBCHANNEL_REF_FROM_WEAK_REF(p, r) (p)->RefFromWeakRef()
+#define GRPC_SUBCHANNEL_UNREF(p, r) (p)->Unref()
+#define GRPC_SUBCHANNEL_WEAK_REF(p, r) (p)->WeakRef()
+#define GRPC_SUBCHANNEL_WEAK_UNREF(p, r) (p)->WeakUnref()
 #define GRPC_SUBCHANNEL_REF_EXTRA_ARGS
+#define GRPC_SUBCHANNEL_REF_REASON ""
+#define GRPC_SUBCHANNEL_REF_MUTATE_EXTRA_ARGS
+#define GRPC_SUBCHANNEL_REF_MUTATE_PURPOSE(x)
 #endif
 
 namespace grpc_core {
 
-class ConnectedSubchannel : public RefCounted<ConnectedSubchannel> {
+class SubchannelCall;
+
+class ConnectedSubchannel : public ConnectedSubchannelInterface {
  public:
   struct CallArgs {
     grpc_polling_entity* pollent;
     grpc_slice path;
     gpr_timespec start_time;
     grpc_millis deadline;
-    gpr_arena* arena;
+    Arena* arena;
     grpc_call_context_element* context;
-    grpc_call_combiner* call_combiner;
+    CallCombiner* call_combiner;
     size_t parent_data_size;
   };
 
   ConnectedSubchannel(
       grpc_channel_stack* channel_stack, const grpc_channel_args* args,
-      grpc_core::RefCountedPtr<grpc_core::channelz::SubchannelNode>
-          channelz_subchannel,
+      RefCountedPtr<channelz::SubchannelNode> channelz_subchannel,
       intptr_t socket_uuid);
   ~ConnectedSubchannel();
 
@@ -96,10 +93,11 @@ class ConnectedSubchannel : public RefCounted<ConnectedSubchannel> {
                            grpc_connectivity_state* state,
                            grpc_closure* closure);
   void Ping(grpc_closure* on_initiate, grpc_closure* on_ack);
-  grpc_error* CreateCall(const CallArgs& args, grpc_subchannel_call** call);
+  RefCountedPtr<SubchannelCall> CreateCall(const CallArgs& args,
+                                           grpc_error** error);
 
   grpc_channel_stack* channel_stack() const { return channel_stack_; }
-  const grpc_channel_args* args() const { return args_; }
+  const grpc_channel_args* args() const override { return args_; }
   channelz::SubchannelNode* channelz_subchannel() const {
     return channelz_subchannel_.get();
   }
@@ -112,107 +110,276 @@ class ConnectedSubchannel : public RefCounted<ConnectedSubchannel> {
   grpc_channel_args* args_;
   // ref counted pointer to the channelz node in this connected subchannel's
   // owning subchannel.
-  grpc_core::RefCountedPtr<grpc_core::channelz::SubchannelNode>
-      channelz_subchannel_;
+  RefCountedPtr<channelz::SubchannelNode> channelz_subchannel_;
   // uuid of this subchannel's socket. 0 if this subchannel is not connected.
   const intptr_t socket_uuid_;
 };
 
-}  // namespace grpc_core
+// Implements the interface of RefCounted<>.
+class SubchannelCall {
+ public:
+  SubchannelCall(RefCountedPtr<ConnectedSubchannel> connected_subchannel,
+                 const ConnectedSubchannel::CallArgs& args)
+      : connected_subchannel_(std::move(connected_subchannel)),
+        deadline_(args.deadline) {}
+
+  // Continues processing a transport stream op batch.
+  void StartTransportStreamOpBatch(grpc_transport_stream_op_batch* batch);
+
+  // Returns a pointer to the parent data associated with the subchannel call.
+  // The data will be of the size specified in \a parent_data_size field of
+  // the args passed to \a ConnectedSubchannel::CreateCall().
+  void* GetParentData();
 
-grpc_subchannel* grpc_subchannel_ref(
-    grpc_subchannel* channel GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-grpc_subchannel* grpc_subchannel_ref_from_weak_ref(
-    grpc_subchannel* channel GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-void grpc_subchannel_unref(
-    grpc_subchannel* channel GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-grpc_subchannel* grpc_subchannel_weak_ref(
-    grpc_subchannel* channel GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-void grpc_subchannel_weak_unref(
-    grpc_subchannel* channel GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-grpc_subchannel_call* grpc_subchannel_call_ref(
-    grpc_subchannel_call* call GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-void grpc_subchannel_call_unref(
-    grpc_subchannel_call* call GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
-
-grpc_core::channelz::SubchannelNode* grpc_subchannel_get_channelz_node(
-    grpc_subchannel* subchannel);
-
-intptr_t grpc_subchannel_get_child_socket_uuid(grpc_subchannel* subchannel);
-
-/** Returns a pointer to the parent data associated with \a subchannel_call.
-    The data will be of the size specified in \a parent_data_size
-    field of the args passed to \a grpc_connected_subchannel_create_call(). */
-void* grpc_connected_subchannel_call_get_parent_data(
-    grpc_subchannel_call* subchannel_call);
-
-/** poll the current connectivity state of a channel */
-grpc_connectivity_state grpc_subchannel_check_connectivity(
-    grpc_subchannel* channel, grpc_error** error, bool inhibit_health_checking);
-
-/** Calls notify when the connectivity state of a channel becomes different
-    from *state.  Updates *state with the new state of the channel. */
-void grpc_subchannel_notify_on_state_change(
-    grpc_subchannel* channel, grpc_pollset_set* interested_parties,
-    grpc_connectivity_state* state, grpc_closure* notify,
-    bool inhibit_health_checks);
-
-/** retrieve the grpc_core::ConnectedSubchannel - or nullptr if not connected
- * (which may happen before it initially connects or during transient failures)
- * */
-grpc_core::RefCountedPtr<grpc_core::ConnectedSubchannel>
-grpc_subchannel_get_connected_subchannel(grpc_subchannel* c);
-
-/** return the subchannel index key for \a subchannel */
-const grpc_subchannel_key* grpc_subchannel_get_key(
-    const grpc_subchannel* subchannel);
-
-// Resets the connection backoff of the subchannel.
-// TODO(roth): Move connection backoff out of subchannels and up into LB
-// policy code (probably by adding a SubchannelGroup between
-// SubchannelList and SubchannelData), at which point this method can
-// go away.
-void grpc_subchannel_reset_backoff(grpc_subchannel* subchannel);
-
-/** continue processing a transport op */
-void grpc_subchannel_call_process_op(grpc_subchannel_call* subchannel_call,
-                                     grpc_transport_stream_op_batch* op);
-
-/** Must be called once per call. Sets the 'then_schedule_closure' argument for
-    call stack destruction. */
-void grpc_subchannel_call_set_cleanup_closure(
-    grpc_subchannel_call* subchannel_call, grpc_closure* closure);
-
-grpc_call_stack* grpc_subchannel_call_get_call_stack(
-    grpc_subchannel_call* subchannel_call);
-
-struct grpc_subchannel_args {
-  /* When updating this struct, also update subchannel_index.c */
-
-  /** Channel filters for this channel - wrapped factories will likely
-      want to mutate this */
-  const grpc_channel_filter** filters;
-  /** The number of filters in the above array */
-  size_t filter_count;
-  /** Channel arguments to be supplied to the newly created channel */
-  const grpc_channel_args* args;
+  // Returns the call stack of the subchannel call.
+  grpc_call_stack* GetCallStack();
+
+  // Sets the 'then_schedule_closure' argument for call stack destruction.
+  // Must be called once per call.
+  void SetAfterCallStackDestroy(grpc_closure* closure);
+
+  // Interface of RefCounted<>.
+  RefCountedPtr<SubchannelCall> Ref() GRPC_MUST_USE_RESULT;
+  RefCountedPtr<SubchannelCall> Ref(const DebugLocation& location,
+                                    const char* reason) GRPC_MUST_USE_RESULT;
+  // When refcount drops to 0, destroys itself and the associated call stack,
+  // but does NOT free the memory because it's in the call arena.
+  void Unref();
+  void Unref(const DebugLocation& location, const char* reason);
+
+  static void Destroy(void* arg, grpc_error* error);
+
+ private:
+  // Allow RefCountedPtr<> to access IncrementRefCount().
+  template <typename T>
+  friend class RefCountedPtr;
+
+  // If channelz is enabled, intercepts recv_trailing so that we may check the
+  // status and associate it to a subchannel.
+  void MaybeInterceptRecvTrailingMetadata(
+      grpc_transport_stream_op_batch* batch);
+
+  static void RecvTrailingMetadataReady(void* arg, grpc_error* error);
+
+  // Interface of RefCounted<>.
+  void IncrementRefCount();
+  void IncrementRefCount(const DebugLocation& location, const char* reason);
+
+  RefCountedPtr<ConnectedSubchannel> connected_subchannel_;
+  grpc_closure* after_call_stack_destroy_ = nullptr;
+  // State needed to support channelz interception of recv trailing metadata.
+  grpc_closure recv_trailing_metadata_ready_;
+  grpc_closure* original_recv_trailing_metadata_ = nullptr;
+  grpc_metadata_batch* recv_trailing_metadata_ = nullptr;
+  grpc_millis deadline_;
 };
 
-/** create a subchannel given a connector */
-grpc_subchannel* grpc_subchannel_create(grpc_connector* connector,
-                                        const grpc_subchannel_args* args);
+// A subchannel that knows how to connect to exactly one target address. It
+// provides a target for load balancing.
+class Subchannel {
+ public:
+  typedef SubchannelInterface::ConnectivityStateWatcher
+      ConnectivityStateWatcher;
+
+  // The ctor and dtor are not intended to use directly.
+  Subchannel(SubchannelKey* key, grpc_connector* connector,
+             const grpc_channel_args* args);
+  ~Subchannel();
+
+  // Creates a subchannel given \a connector and \a args.
+  static Subchannel* Create(grpc_connector* connector,
+                            const grpc_channel_args* args);
+
+  // Strong and weak refcounting.
+  Subchannel* Ref(GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
+  void Unref(GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
+  Subchannel* WeakRef(GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
+  void WeakUnref(GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
+  // Attempts to return a strong ref when only the weak refcount is guaranteed
+  // non-zero. If the strong refcount is zero, does not alter the refcount and
+  // returns null.
+  Subchannel* RefFromWeakRef(GRPC_SUBCHANNEL_REF_EXTRA_ARGS);
+
+  intptr_t GetChildSocketUuid();
+
+  // Gets the string representing the subchannel address.
+  // Caller doesn't take ownership.
+  const char* GetTargetAddress();
+
+  channelz::SubchannelNode* channelz_node();
+
+  // Returns the current connectivity state of the subchannel.
+  // If health_check_service_name is non-null, the returned connectivity
+  // state will be based on the state reported by the backend for that
+  // service name.
+  // If the return value is GRPC_CHANNEL_READY, also sets *connected_subchannel.
+  grpc_connectivity_state CheckConnectivityState(
+      const char* health_check_service_name,
+      RefCountedPtr<ConnectedSubchannel>* connected_subchannel);
+
+  // Starts watching the subchannel's connectivity state.
+  // The first callback to the watcher will be delivered when the
+  // subchannel's connectivity state becomes a value other than
+  // initial_state, which may happen immediately.
+  // Subsequent callbacks will be delivered as the subchannel's state
+  // changes.
+  // The watcher will be destroyed either when the subchannel is
+  // destroyed or when CancelConnectivityStateWatch() is called.
+  void WatchConnectivityState(grpc_connectivity_state initial_state,
+                              UniquePtr<char> health_check_service_name,
+                              UniquePtr<ConnectivityStateWatcher> watcher);
+
+  // Cancels a connectivity state watch.
+  // If the watcher has already been destroyed, this is a no-op.
+  void CancelConnectivityStateWatch(const char* health_check_service_name,
+                                    ConnectivityStateWatcher* watcher);
+
+  // Attempt to connect to the backend.  Has no effect if already connected.
+  void AttemptToConnect();
+
+  // Resets the connection backoff of the subchannel.
+  // TODO(roth): Move connection backoff out of subchannels and up into LB
+  // policy code (probably by adding a SubchannelGroup between
+  // SubchannelList and SubchannelData), at which point this method can
+  // go away.
+  void ResetBackoff();
+
+  // Returns a new channel arg encoding the subchannel address as a URI
+  // string. Caller is responsible for freeing the string.
+  static grpc_arg CreateSubchannelAddressArg(const grpc_resolved_address* addr);
+
+  // Returns the URI string from the subchannel address arg in \a args.
+  static const char* GetUriFromSubchannelAddressArg(
+      const grpc_channel_args* args);
+
+  // Sets \a addr from the subchannel address arg in \a args.
+  static void GetAddressFromSubchannelAddressArg(const grpc_channel_args* args,
+                                                 grpc_resolved_address* addr);
+
+ private:
+  // A linked list of ConnectivityStateWatchers that are monitoring the
+  // subchannel's state.
+  class ConnectivityStateWatcherList {
+   public:
+    ~ConnectivityStateWatcherList() { Clear(); }
+
+    void AddWatcherLocked(UniquePtr<ConnectivityStateWatcher> watcher);
+    void RemoveWatcherLocked(ConnectivityStateWatcher* watcher);
+
+    // Notifies all watchers in the list about a change to state.
+    void NotifyLocked(Subchannel* subchannel, grpc_connectivity_state state);
+
+    void Clear() { watchers_.clear(); }
+
+    bool empty() const { return watchers_.empty(); }
+
+   private:
+    // TODO(roth): This could be a set instead of a map if we had a set
+    // implementation.
+    Map<ConnectivityStateWatcher*, UniquePtr<ConnectivityStateWatcher>>
+        watchers_;
+  };
 
-/// Sets \a addr from \a args.
-void grpc_get_subchannel_address_arg(const grpc_channel_args* args,
-                                     grpc_resolved_address* addr);
+  // A map that tracks ConnectivityStateWatchers using a particular health
+  // check service name.
+  //
+  // There is one entry in the map for each health check service name.
+  // Entries exist only as long as there are watchers using the
+  // corresponding service name.
+  //
+  // A health check client is maintained only while the subchannel is in
+  // state READY.
+  class HealthWatcherMap {
+   public:
+    void AddWatcherLocked(Subchannel* subchannel,
+                          grpc_connectivity_state initial_state,
+                          UniquePtr<char> health_check_service_name,
+                          UniquePtr<ConnectivityStateWatcher> watcher);
+    void RemoveWatcherLocked(const char* health_check_service_name,
+                             ConnectivityStateWatcher* watcher);
+
+    // Notifies the watcher when the subchannel's state changes.
+    void NotifyLocked(grpc_connectivity_state state);
+
+    grpc_connectivity_state CheckConnectivityStateLocked(
+        Subchannel* subchannel, const char* health_check_service_name);
+
+    void ShutdownLocked();
+
+   private:
+    class HealthWatcher;
+
+    Map<const char*, OrphanablePtr<HealthWatcher>, StringLess> map_;
+  };
+
+  class ConnectedSubchannelStateWatcher;
 
-const char* grpc_subchannel_get_target(grpc_subchannel* subchannel);
+  // Sets the subchannel's connectivity state to \a state.
+  void SetConnectivityStateLocked(grpc_connectivity_state state);
 
-/// Returns the URI string for the address to connect to.
-const char* grpc_get_subchannel_address_uri_arg(const grpc_channel_args* args);
+  // Methods for connection.
+  void MaybeStartConnectingLocked();
+  static void OnRetryAlarm(void* arg, grpc_error* error);
+  void ContinueConnectingLocked();
+  static void OnConnectingFinished(void* arg, grpc_error* error);
+  bool PublishTransportLocked();
+  void Disconnect();
 
-/// Returns a new channel arg encoding the subchannel address as a string.
-/// Caller is responsible for freeing the string.
-grpc_arg grpc_create_subchannel_address_arg(const grpc_resolved_address* addr);
+  gpr_atm RefMutate(gpr_atm delta,
+                    int barrier GRPC_SUBCHANNEL_REF_MUTATE_EXTRA_ARGS);
+
+  // The subchannel pool this subchannel is in.
+  RefCountedPtr<SubchannelPoolInterface> subchannel_pool_;
+  // TODO(juanlishen): Consider using args_ as key_ directly.
+  // Subchannel key that identifies this subchannel in the subchannel pool.
+  SubchannelKey* key_;
+  // Channel args.
+  grpc_channel_args* args_;
+  // pollset_set tracking who's interested in a connection being setup.
+  grpc_pollset_set* pollset_set_;
+  // Protects the other members.
+  Mutex mu_;
+  // Refcount
+  //    - lower INTERNAL_REF_BITS bits are for internal references:
+  //      these do not keep the subchannel open.
+  //    - upper remaining bits are for public references: these do
+  //      keep the subchannel open
+  gpr_atm ref_pair_;
+
+  // Connection states.
+  grpc_connector* connector_ = nullptr;
+  // Set during connection.
+  grpc_connect_out_args connecting_result_;
+  grpc_closure on_connecting_finished_;
+  // Active connection, or null.
+  RefCountedPtr<ConnectedSubchannel> connected_subchannel_;
+  bool connecting_ = false;
+  bool disconnected_ = false;
+
+  // Connectivity state tracking.
+  grpc_connectivity_state state_ = GRPC_CHANNEL_IDLE;
+  // The list of watchers without a health check service name.
+  ConnectivityStateWatcherList watcher_list_;
+  // The map of watchers with health check service names.
+  HealthWatcherMap health_watcher_map_;
+
+  // Backoff state.
+  BackOff backoff_;
+  grpc_millis next_attempt_deadline_;
+  grpc_millis min_connect_timeout_ms_;
+  bool backoff_begun_ = false;
+
+  // Retry alarm.
+  grpc_timer retry_alarm_;
+  grpc_closure on_retry_alarm_;
+  bool have_retry_alarm_ = false;
+  // reset_backoff() was called while alarm was pending.
+  bool retry_immediately_ = false;
+
+  // Channelz tracking.
+  RefCountedPtr<channelz::SubchannelNode> channelz_node_;
+};
+
+}  // namespace grpc_core
 
 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_H */

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

@@ -0,0 +1,113 @@
+/*
+ *
+ * Copyright 2019 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_SUBCHANNEL_INTERFACE_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_INTERFACE_H
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/debug/trace.h"
+#include "src/core/lib/gprpp/ref_counted.h"
+#include "src/core/lib/gprpp/ref_counted_ptr.h"
+
+namespace grpc_core {
+
+// TODO(roth): In a subsequent PR, remove this from this API.
+class ConnectedSubchannelInterface
+    : public RefCounted<ConnectedSubchannelInterface> {
+ public:
+  virtual const grpc_channel_args* args() const GRPC_ABSTRACT;
+
+ protected:
+  template <typename TraceFlagT = TraceFlag>
+  explicit ConnectedSubchannelInterface(TraceFlagT* trace_flag = nullptr)
+      : RefCounted<ConnectedSubchannelInterface>(trace_flag) {}
+};
+
+class SubchannelInterface : public RefCounted<SubchannelInterface> {
+ public:
+  class ConnectivityStateWatcher {
+   public:
+    virtual ~ConnectivityStateWatcher() = default;
+
+    // Will be invoked whenever the subchannel's connectivity state
+    // changes.  There will be only one invocation of this method on a
+    // given watcher instance at any given time.
+    //
+    // When the state changes to READY, connected_subchannel will
+    // contain a ref to the connected subchannel.  When it changes from
+    // READY to some other state, the implementation must release its
+    // ref to the connected subchannel.
+    virtual void OnConnectivityStateChange(
+        grpc_connectivity_state new_state,
+        RefCountedPtr<ConnectedSubchannelInterface>
+            connected_subchannel)  // NOLINT
+        GRPC_ABSTRACT;
+
+    // TODO(roth): Remove this as soon as we move to EventManager-based
+    // polling.
+    virtual grpc_pollset_set* interested_parties() GRPC_ABSTRACT;
+
+    GRPC_ABSTRACT_BASE_CLASS
+  };
+
+  virtual ~SubchannelInterface() = default;
+
+  // Returns the current connectivity state of the subchannel.
+  virtual grpc_connectivity_state CheckConnectivityState(
+      RefCountedPtr<ConnectedSubchannelInterface>* connected_subchannel)
+      GRPC_ABSTRACT;
+
+  // Starts watching the subchannel's connectivity state.
+  // The first callback to the watcher will be delivered when the
+  // subchannel's connectivity state becomes a value other than
+  // initial_state, which may happen immediately.
+  // Subsequent callbacks will be delivered as the subchannel's state
+  // changes.
+  // The watcher will be destroyed either when the subchannel is
+  // destroyed or when CancelConnectivityStateWatch() is called.
+  // There can be only one watcher of a given subchannel.  It is not
+  // valid to call this method a second time without first cancelling
+  // the previous watcher using CancelConnectivityStateWatch().
+  virtual void WatchConnectivityState(
+      grpc_connectivity_state initial_state,
+      UniquePtr<ConnectivityStateWatcher> watcher) GRPC_ABSTRACT;
+
+  // Cancels a connectivity state watch.
+  // If the watcher has already been destroyed, this is a no-op.
+  virtual void CancelConnectivityStateWatch(ConnectivityStateWatcher* watcher)
+      GRPC_ABSTRACT;
+
+  // Attempt to connect to the backend.  Has no effect if already connected.
+  // If the subchannel is currently in backoff delay due to a previously
+  // failed attempt, the new connection attempt will not start until the
+  // backoff delay has elapsed.
+  virtual void AttemptToConnect() GRPC_ABSTRACT;
+
+  // Resets the subchannel's connection backoff state.  If AttemptToConnect()
+  // has been called since the subchannel entered TRANSIENT_FAILURE state,
+  // starts a new connection attempt immediately; otherwise, a new connection
+  // attempt will be started as soon as AttemptToConnect() is called.
+  virtual void ResetBackoff() GRPC_ABSTRACT;
+
+  GRPC_ABSTRACT_BASE_CLASS
+};
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_INTERFACE_H */