legacy-libs/grpc/deps/grpc/src/core/ext/filters/client_channel/subchannel_interface.h

   1 /*
   2  *
   3  * Copyright 2019 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_INTERFACE_H
  20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_INTERFACE_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include "src/core/lib/gprpp/ref_counted.h"
  25 #include "src/core/lib/gprpp/ref_counted_ptr.h"
  26
  27 namespace grpc_core {
  28
  29 // The interface for subchannels that is exposed to LB policy implementations.
  30 class SubchannelInterface : public RefCounted<SubchannelInterface> {
  31  public:
  32   class ConnectivityStateWatcherInterface {
  33    public:
  34     virtual ~ConnectivityStateWatcherInterface() = default;
  35
  36     // Will be invoked whenever the subchannel's connectivity state
  37     // changes.  There will be only one invocation of this method on a
  38     // given watcher instance at any given time.
  39     virtual void OnConnectivityStateChange(grpc_connectivity_state new_state)
  40         GRPC_ABSTRACT;
  41
  42     // TODO(roth): Remove this as soon as we move to EventManager-based
  43     // polling.
  44     virtual grpc_pollset_set* interested_parties() GRPC_ABSTRACT;
  45
  46     GRPC_ABSTRACT_BASE_CLASS
  47   };
  48
  49   template <typename TraceFlagT = TraceFlag>
  50   explicit SubchannelInterface(TraceFlagT* trace_flag = nullptr)
  51       : RefCounted<SubchannelInterface>(trace_flag) {}
  52
  53   virtual ~SubchannelInterface() = default;
  54
  55   // Returns the current connectivity state of the subchannel.
  56   virtual grpc_connectivity_state CheckConnectivityState() GRPC_ABSTRACT;
  57
  58   // Starts watching the subchannel's connectivity state.
  59   // The first callback to the watcher will be delivered when the
  60   // subchannel's connectivity state becomes a value other than
  61   // initial_state, which may happen immediately.
  62   // Subsequent callbacks will be delivered as the subchannel's state
  63   // changes.
  64   // The watcher will be destroyed either when the subchannel is
  65   // destroyed or when CancelConnectivityStateWatch() is called.
  66   // There can be only one watcher of a given subchannel.  It is not
  67   // valid to call this method a second time without first cancelling
  68   // the previous watcher using CancelConnectivityStateWatch().
  69   virtual void WatchConnectivityState(
  70       grpc_connectivity_state initial_state,
  71       UniquePtr<ConnectivityStateWatcherInterface> watcher) GRPC_ABSTRACT;
  72
  73   // Cancels a connectivity state watch.
  74   // If the watcher has already been destroyed, this is a no-op.
  75   virtual void CancelConnectivityStateWatch(
  76       ConnectivityStateWatcherInterface* watcher) GRPC_ABSTRACT;
  77
  78   // Attempt to connect to the backend.  Has no effect if already connected.
  79   // If the subchannel is currently in backoff delay due to a previously
  80   // failed attempt, the new connection attempt will not start until the
  81   // backoff delay has elapsed.
  82   virtual void AttemptToConnect() GRPC_ABSTRACT;
  83
  84   // Resets the subchannel's connection backoff state.  If AttemptToConnect()
  85   // has been called since the subchannel entered TRANSIENT_FAILURE state,
  86   // starts a new connection attempt immediately; otherwise, a new connection
  87   // attempt will be started as soon as AttemptToConnect() is called.
  88   virtual void ResetBackoff() GRPC_ABSTRACT;
  89
  90   // TODO(roth): Need a better non-grpc-specific abstraction here.
  91   virtual const grpc_channel_args* channel_args() GRPC_ABSTRACT;
  92
  93   GRPC_ABSTRACT_BASE_CLASS
  94 };
  95
  96 }  // namespace grpc_core
  97
  98 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_SUBCHANNEL_INTERFACE_H */