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