1 // 2 // Copyright 2019 gRPC authors. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 17 #ifndef GRPC_SRC_CORE_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H 18 #define GRPC_SRC_CORE_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H 19 20 #include <grpc/impl/connectivity_state.h> 21 #include <grpc/support/port_platform.h> 22 23 #include <memory> 24 #include <utility> 25 26 #include "absl/status/status.h" 27 #include "absl/strings/string_view.h" 28 #include "src/core/lib/iomgr/iomgr_fwd.h" 29 #include "src/core/util/dual_ref_counted.h" 30 #include "src/core/util/ref_counted_ptr.h" 31 32 namespace grpc_core { 33 34 // The interface for subchannels that is exposed to LB policy implementations. 35 class SubchannelInterface : public DualRefCounted<SubchannelInterface> { 36 public: 37 class ConnectivityStateWatcherInterface { 38 public: 39 virtual ~ConnectivityStateWatcherInterface() = default; 40 41 // Will be invoked whenever the subchannel's connectivity state changes. 42 // If the new state is TRANSIENT_FAILURE, status indicates the reason 43 // for the failure. There will be only one invocation of this method 44 // on a given watcher instance at any given time. 45 virtual void OnConnectivityStateChange(grpc_connectivity_state new_state, 46 absl::Status status) = 0; 47 48 // TODO(roth): Remove this as soon as we move to EventManager-based 49 // polling. 50 virtual grpc_pollset_set* interested_parties() = 0; 51 }; 52 53 // Opaque interface for watching data of a particular type for this 54 // subchannel. 55 class DataWatcherInterface { 56 public: 57 virtual ~DataWatcherInterface() = default; 58 }; 59 60 explicit SubchannelInterface(const char* trace = nullptr) 61 : DualRefCounted<SubchannelInterface>(trace) {} 62 63 ~SubchannelInterface() override = default; 64 65 // Starts watching the subchannel's connectivity state. 66 // The first callback to the watcher will be delivered ~immediately. 67 // Subsequent callbacks will be delivered as the subchannel's state 68 // changes. 69 // The watcher will be destroyed either when the subchannel is 70 // destroyed or when CancelConnectivityStateWatch() is called. 71 // There can be only one watcher of a given subchannel. It is not 72 // valid to call this method a second time without first cancelling 73 // the previous watcher using CancelConnectivityStateWatch(). 74 virtual void WatchConnectivityState( 75 std::unique_ptr<ConnectivityStateWatcherInterface> watcher) = 0; 76 77 // Cancels a connectivity state watch. 78 // If the watcher has already been destroyed, this is a no-op. 79 // TODO(roth): This interface has an ABA issue. Fix this before we 80 // make this API public. 81 virtual void CancelConnectivityStateWatch( 82 ConnectivityStateWatcherInterface* watcher) = 0; 83 84 // Attempt to connect to the backend. Has no effect if already connected. 85 // If the subchannel is currently in backoff delay due to a previously 86 // failed attempt, the new connection attempt will not start until the 87 // backoff delay has elapsed. 88 virtual void RequestConnection() = 0; 89 90 // Resets the subchannel's connection backoff state. If RequestConnection() 91 // has been called since the subchannel entered TRANSIENT_FAILURE state, 92 // starts a new connection attempt immediately; otherwise, a new connection 93 // attempt will be started as soon as RequestConnection() is called. 94 virtual void ResetBackoff() = 0; 95 96 // Registers a new data watcher. 97 virtual void AddDataWatcher( 98 std::unique_ptr<DataWatcherInterface> watcher) = 0; 99 100 // Cancels a data watch. 101 // TODO(roth): This interface has an ABA issue. Fix this before we 102 // make this API public. 103 virtual void CancelDataWatcher(DataWatcherInterface* watcher) = 0; 104 105 // Return the address in URI format. 106 virtual std::string address() const = 0; 107 108 protected: Orphaned()109 void Orphaned() override {} 110 }; 111 112 // A class that delegates to another subchannel, to be used in cases 113 // where an LB policy needs to wrap a subchannel. 114 class DelegatingSubchannel : public SubchannelInterface { 115 public: DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel)116 explicit DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel) 117 : wrapped_subchannel_(std::move(subchannel)) {} 118 wrapped_subchannel()119 RefCountedPtr<SubchannelInterface> wrapped_subchannel() const { 120 return wrapped_subchannel_; 121 } 122 WatchConnectivityState(std::unique_ptr<ConnectivityStateWatcherInterface> watcher)123 void WatchConnectivityState( 124 std::unique_ptr<ConnectivityStateWatcherInterface> watcher) override { 125 return wrapped_subchannel_->WatchConnectivityState(std::move(watcher)); 126 } CancelConnectivityStateWatch(ConnectivityStateWatcherInterface * watcher)127 void CancelConnectivityStateWatch( 128 ConnectivityStateWatcherInterface* watcher) override { 129 return wrapped_subchannel_->CancelConnectivityStateWatch(watcher); 130 } RequestConnection()131 void RequestConnection() override { 132 wrapped_subchannel_->RequestConnection(); 133 } ResetBackoff()134 void ResetBackoff() override { wrapped_subchannel_->ResetBackoff(); } AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher)135 void AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher) override { 136 wrapped_subchannel_->AddDataWatcher(std::move(watcher)); 137 } CancelDataWatcher(DataWatcherInterface * watcher)138 void CancelDataWatcher(DataWatcherInterface* watcher) override { 139 wrapped_subchannel_->CancelDataWatcher(watcher); 140 } 141 address()142 std::string address() const override { 143 return wrapped_subchannel_->address(); 144 } 145 146 private: 147 RefCountedPtr<SubchannelInterface> wrapped_subchannel_; 148 }; 149 150 } // namespace grpc_core 151 152 #endif // GRPC_SRC_CORE_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H 153