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_LIB_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H
18 #define GRPC_SRC_CORE_LIB_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 
Orphan()66   void Orphan() override {}
67 
68   // Starts watching the subchannel's connectivity state.
69   // The first callback to the watcher will be delivered ~immediately.
70   // Subsequent callbacks will be delivered as the subchannel's state
71   // changes.
72   // The watcher will be destroyed either when the subchannel is
73   // destroyed or when CancelConnectivityStateWatch() is called.
74   // There can be only one watcher of a given subchannel.  It is not
75   // valid to call this method a second time without first cancelling
76   // the previous watcher using CancelConnectivityStateWatch().
77   virtual void WatchConnectivityState(
78       std::unique_ptr<ConnectivityStateWatcherInterface> watcher) = 0;
79 
80   // Cancels a connectivity state watch.
81   // If the watcher has already been destroyed, this is a no-op.
82   virtual void CancelConnectivityStateWatch(
83       ConnectivityStateWatcherInterface* watcher) = 0;
84 
85   // Attempt to connect to the backend.  Has no effect if already connected.
86   // If the subchannel is currently in backoff delay due to a previously
87   // failed attempt, the new connection attempt will not start until the
88   // backoff delay has elapsed.
89   virtual void RequestConnection() = 0;
90 
91   // Resets the subchannel's connection backoff state.  If RequestConnection()
92   // has been called since the subchannel entered TRANSIENT_FAILURE state,
93   // starts a new connection attempt immediately; otherwise, a new connection
94   // attempt will be started as soon as RequestConnection() is called.
95   virtual void ResetBackoff() = 0;
96 
97   // Registers a new data watcher.
98   virtual void AddDataWatcher(
99       std::unique_ptr<DataWatcherInterface> watcher) = 0;
100 };
101 
102 // A class that delegates to another subchannel, to be used in cases
103 // where an LB policy needs to wrap a subchannel.
104 class DelegatingSubchannel : public SubchannelInterface {
105  public:
DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel)106   explicit DelegatingSubchannel(RefCountedPtr<SubchannelInterface> subchannel)
107       : wrapped_subchannel_(std::move(subchannel)) {}
108 
wrapped_subchannel()109   RefCountedPtr<SubchannelInterface> wrapped_subchannel() const {
110     return wrapped_subchannel_;
111   }
112 
WatchConnectivityState(std::unique_ptr<ConnectivityStateWatcherInterface> watcher)113   void WatchConnectivityState(
114       std::unique_ptr<ConnectivityStateWatcherInterface> watcher) override {
115     return wrapped_subchannel_->WatchConnectivityState(std::move(watcher));
116   }
CancelConnectivityStateWatch(ConnectivityStateWatcherInterface * watcher)117   void CancelConnectivityStateWatch(
118       ConnectivityStateWatcherInterface* watcher) override {
119     return wrapped_subchannel_->CancelConnectivityStateWatch(watcher);
120   }
RequestConnection()121   void RequestConnection() override {
122     wrapped_subchannel_->RequestConnection();
123   }
ResetBackoff()124   void ResetBackoff() override { wrapped_subchannel_->ResetBackoff(); }
AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher)125   void AddDataWatcher(std::unique_ptr<DataWatcherInterface> watcher) override {
126     wrapped_subchannel_->AddDataWatcher(std::move(watcher));
127   }
128 
129  private:
130   RefCountedPtr<SubchannelInterface> wrapped_subchannel_;
131 };
132 
133 }  // namespace grpc_core
134 
135 #endif  // GRPC_SRC_CORE_LIB_LOAD_BALANCING_SUBCHANNEL_INTERFACE_H
136