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/support/port_platform.h> 21 22 #include <memory> 23 #include <utility> 24 25 #include "absl/status/status.h" 26 27 #include <grpc/impl/connectivity_state.h> 28 29 #include "src/core/lib/gprpp/dual_ref_counted.h" 30 #include "src/core/lib/gprpp/ref_counted_ptr.h" 31 #include "src/core/lib/iomgr/iomgr_fwd.h" 32 33 namespace grpc_core { 34 35 // The interface for subchannels that is exposed to LB policy implementations. 36 class SubchannelInterface : public DualRefCounted<SubchannelInterface> { 37 public: 38 class ConnectivityStateWatcherInterface { 39 public: 40 virtual ~ConnectivityStateWatcherInterface() = default; 41 42 // Will be invoked whenever the subchannel's connectivity state changes. 43 // If the new state is TRANSIENT_FAILURE, status indicates the reason 44 // for the failure. There will be only one invocation of this method 45 // on a given watcher instance at any given time. 46 virtual void OnConnectivityStateChange(grpc_connectivity_state new_state, 47 absl::Status status) = 0; 48 49 // TODO(roth): Remove this as soon as we move to EventManager-based 50 // polling. 51 virtual grpc_pollset_set* interested_parties() = 0; 52 }; 53 54 // Opaque interface for watching data of a particular type for this 55 // subchannel. 56 class DataWatcherInterface { 57 public: 58 virtual ~DataWatcherInterface() = default; 59 }; 60 61 explicit SubchannelInterface(const char* trace = nullptr) 62 : DualRefCounted<SubchannelInterface>(trace) {} 63 64 ~SubchannelInterface() override = default; 65 66 // Starts watching the subchannel's connectivity state. 67 // The first callback to the watcher will be delivered ~immediately. 68 // Subsequent callbacks will be delivered as the subchannel's state 69 // changes. 70 // The watcher will be destroyed either when the subchannel is 71 // destroyed or when CancelConnectivityStateWatch() is called. 72 // There can be only one watcher of a given subchannel. It is not 73 // valid to call this method a second time without first cancelling 74 // the previous watcher using CancelConnectivityStateWatch(). 75 virtual void WatchConnectivityState( 76 std::unique_ptr<ConnectivityStateWatcherInterface> watcher) = 0; 77 78 // Cancels a connectivity state watch. 79 // If the watcher has already been destroyed, this is a no-op. 80 virtual void CancelConnectivityStateWatch( 81 ConnectivityStateWatcherInterface* watcher) = 0; 82 83 // Attempt to connect to the backend. Has no effect if already connected. 84 // If the subchannel is currently in backoff delay due to a previously 85 // failed attempt, the new connection attempt will not start until the 86 // backoff delay has elapsed. 87 virtual void RequestConnection() = 0; 88 89 // Resets the subchannel's connection backoff state. If RequestConnection() 90 // has been called since the subchannel entered TRANSIENT_FAILURE state, 91 // starts a new connection attempt immediately; otherwise, a new connection 92 // attempt will be started as soon as RequestConnection() is called. 93 virtual void ResetBackoff() = 0; 94 95 // Registers a new data watcher. 96 virtual void AddDataWatcher( 97 std::unique_ptr<DataWatcherInterface> watcher) = 0; 98 99 // Cancels a data watch. 100 virtual void CancelDataWatcher(DataWatcherInterface* watcher) = 0; 101 102 protected: Orphaned()103 void Orphaned() override {} 104 }; 105 106 // A class that delegates to another subchannel, to be used in cases 107 // where an LB policy needs to wrap a subchannel. 108 class DelegatingSubchannel : public SubchannelInterface { 109 public: DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel)110 explicit DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel) 111 : wrapped_subchannel_(std::move(subchannel)) {} 112 wrapped_subchannel()113 RefCountedPtr<SubchannelInterface> wrapped_subchannel() const { 114 return wrapped_subchannel_; 115 } 116 WatchConnectivityState(std::unique_ptr<ConnectivityStateWatcherInterface> watcher)117 void WatchConnectivityState( 118 std::unique_ptr<ConnectivityStateWatcherInterface> watcher) override { 119 return wrapped_subchannel_->WatchConnectivityState(std::move(watcher)); 120 } CancelConnectivityStateWatch(ConnectivityStateWatcherInterface * watcher)121 void CancelConnectivityStateWatch( 122 ConnectivityStateWatcherInterface* watcher) override { 123 return wrapped_subchannel_->CancelConnectivityStateWatch(watcher); 124 } RequestConnection()125 void RequestConnection() override { 126 wrapped_subchannel_->RequestConnection(); 127 } ResetBackoff()128 void ResetBackoff() override { wrapped_subchannel_->ResetBackoff(); } AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher)129 void AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher) override { 130 wrapped_subchannel_->AddDataWatcher(std::move(watcher)); 131 } CancelDataWatcher(DataWatcherInterface * watcher)132 void CancelDataWatcher(DataWatcherInterface* watcher) override { 133 wrapped_subchannel_->CancelDataWatcher(watcher); 134 } 135 136 private: 137 RefCountedPtr<SubchannelInterface> wrapped_subchannel_; 138 }; 139 140 } // namespace grpc_core 141 142 #endif // GRPC_SRC_CORE_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H 143