1 //
2 // Copyright 2024 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_SURFACE_CHANNEL_H
18 #define GRPC_SRC_CORE_LIB_SURFACE_CHANNEL_H
19
20 #include <grpc/support/port_platform.h>
21
22 #include <map>
23 #include <string>
24
25 #include "absl/base/thread_annotations.h"
26 #include "absl/status/statusor.h"
27 #include "absl/strings/string_view.h"
28 #include "absl/types/optional.h"
29
30 #include <grpc/event_engine/event_engine.h>
31 #include <grpc/grpc.h>
32 #include <grpc/impl/compression_types.h>
33 #include <grpc/support/time.h>
34
35 #include "src/core/lib/channel/channel_args.h"
36 #include "src/core/lib/channel/channelz.h"
37 #include "src/core/lib/gprpp/cpp_impl_of.h"
38 #include "src/core/lib/gprpp/ref_counted.h"
39 #include "src/core/lib/gprpp/ref_counted_ptr.h"
40 #include "src/core/lib/gprpp/sync.h"
41 #include "src/core/lib/gprpp/time.h"
42 #include "src/core/lib/iomgr/iomgr_fwd.h"
43 #include "src/core/lib/resource_quota/arena.h"
44 #include "src/core/lib/slice/slice.h"
45 #include "src/core/lib/surface/channel_stack_type.h"
46 #include "src/core/lib/transport/connectivity_state.h"
47
48 // Forward declaration to avoid dependency loop.
49 struct grpc_channel_stack;
50
51 namespace grpc_core {
52
53 // Forward declaration to avoid dependency loop.
54 class Transport;
55
56 class Channel : public RefCounted<Channel>,
57 public CppImplOf<Channel, grpc_channel> {
58 public:
59 struct RegisteredCall {
60 Slice path;
61 absl::optional<Slice> authority;
62
63 explicit RegisteredCall(const char* method_arg, const char* host_arg);
64 RegisteredCall(const RegisteredCall& other);
65 RegisteredCall& operator=(const RegisteredCall&) = delete;
66
67 ~RegisteredCall();
68 };
69
70 virtual void Orphan() = 0;
71
72 virtual Arena* CreateArena() = 0;
73 virtual void DestroyArena(Arena* arena) = 0;
74
75 virtual bool IsLame() const = 0;
76
77 // TODO(roth): This should return a C++ type.
78 virtual grpc_call* CreateCall(grpc_call* parent_call,
79 uint32_t propagation_mask,
80 grpc_completion_queue* cq,
81 grpc_pollset_set* pollset_set_alternative,
82 Slice path, absl::optional<Slice> authority,
83 Timestamp deadline, bool registered_method) = 0;
84
85 virtual grpc_event_engine::experimental::EventEngine* event_engine()
86 const = 0;
87
88 virtual bool SupportsConnectivityWatcher() const = 0;
89
90 virtual grpc_connectivity_state CheckConnectivityState(
91 bool try_to_connect) = 0;
92
93 // For external watched via the C-core API.
94 virtual void WatchConnectivityState(
95 grpc_connectivity_state last_observed_state, Timestamp deadline,
96 grpc_completion_queue* cq, void* tag) = 0;
97
98 // For internal watches.
99 virtual void AddConnectivityWatcher(
100 grpc_connectivity_state initial_state,
101 OrphanablePtr<AsyncConnectivityStateWatcherInterface> watcher) = 0;
102 virtual void RemoveConnectivityWatcher(
103 AsyncConnectivityStateWatcherInterface* watcher) = 0;
104
105 virtual void GetInfo(const grpc_channel_info* channel_info) = 0;
106
107 virtual void ResetConnectionBackoff() = 0;
108
target()109 absl::string_view target() const { return target_; }
channelz_node()110 channelz::ChannelNode* channelz_node() const { return channelz_node_.get(); }
compression_options()111 grpc_compression_options compression_options() const {
112 return compression_options_;
113 }
114
115 RegisteredCall* RegisterCall(const char* method, const char* host);
116
TestOnlyRegisteredCalls()117 int TestOnlyRegisteredCalls() {
118 MutexLock lock(&mu_);
119 return registration_table_.size();
120 }
121
122 // For tests only.
123 // Pings the channel's peer. Load-balanced channels will select one
124 // subchannel to ping. If the channel is not connected, posts a
125 // failure to the CQ.
126 virtual void Ping(grpc_completion_queue* cq, void* tag) = 0;
127
128 // TODO(roth): Remove these methods when LegacyChannel goes away.
channel_stack()129 virtual grpc_channel_stack* channel_stack() const { return nullptr; }
is_client()130 virtual bool is_client() const { return true; }
is_promising()131 virtual bool is_promising() const { return true; }
132
133 protected:
134 Channel(std::string target, const ChannelArgs& channel_args);
135
136 private:
137 const std::string target_;
138 const RefCountedPtr<channelz::ChannelNode> channelz_node_;
139 const grpc_compression_options compression_options_;
140
141 Mutex mu_;
142 // The map key needs to be owned strings rather than unowned char*'s to
143 // guarantee that it outlives calls on the core channel (which may outlast
144 // the C++ or other wrapped language Channel that registered these calls).
145 std::map<std::pair<std::string, std::string>, RegisteredCall>
146 registration_table_ ABSL_GUARDED_BY(mu_);
147 };
148
149 } // namespace grpc_core
150
151 /// The same as grpc_channel_destroy, but doesn't create an ExecCtx, and so
152 /// is safe to use from within core.
grpc_channel_destroy_internal(grpc_channel * channel)153 inline void grpc_channel_destroy_internal(grpc_channel* channel) {
154 grpc_core::Channel::FromC(channel)->Orphan();
155 }
156
157 // Return the channel's compression options.
grpc_channel_compression_options(const grpc_channel * channel)158 inline grpc_compression_options grpc_channel_compression_options(
159 const grpc_channel* channel) {
160 return grpc_core::Channel::FromC(channel)->compression_options();
161 }
162
grpc_channel_get_channelz_node(grpc_channel * channel)163 inline grpc_core::channelz::ChannelNode* grpc_channel_get_channelz_node(
164 grpc_channel* channel) {
165 return grpc_core::Channel::FromC(channel)->channelz_node();
166 }
167
168 // Ping the channels peer (load balanced channels will select one sub-channel to
169 // ping); if the channel is not connected, posts a failed.
170 void grpc_channel_ping(grpc_channel* channel, grpc_completion_queue* cq,
171 void* tag, void* reserved);
172
173 #endif // GRPC_SRC_CORE_LIB_SURFACE_CHANNEL_H
174