1 // 2 // 3 // Copyright 2015 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPC_SRC_CORE_LIB_SURFACE_CALL_H 20 #define GRPC_SRC_CORE_LIB_SURFACE_CALL_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <stddef.h> 25 #include <stdint.h> 26 27 #include "absl/functional/any_invocable.h" 28 #include "absl/functional/function_ref.h" 29 #include "absl/strings/string_view.h" 30 #include "absl/types/optional.h" 31 32 #include <grpc/grpc.h> 33 #include <grpc/impl/compression_types.h> 34 #include <grpc/support/atm.h> 35 #include <grpc/support/log.h> 36 37 #include "src/core/lib/channel/channel_fwd.h" 38 #include "src/core/lib/channel/channel_stack.h" 39 #include "src/core/lib/channel/context.h" 40 #include "src/core/lib/debug/trace.h" 41 #include "src/core/lib/gprpp/ref_counted_ptr.h" 42 #include "src/core/lib/gprpp/time.h" 43 #include "src/core/lib/iomgr/closure.h" 44 #include "src/core/lib/iomgr/error.h" 45 #include "src/core/lib/iomgr/iomgr_fwd.h" 46 #include "src/core/lib/promise/arena_promise.h" 47 #include "src/core/lib/promise/context.h" 48 #include "src/core/lib/resource_quota/arena.h" 49 #include "src/core/lib/slice/slice.h" 50 #include "src/core/lib/surface/api_trace.h" 51 #include "src/core/lib/surface/channel.h" 52 #include "src/core/lib/surface/server.h" 53 #include "src/core/lib/transport/transport.h" 54 55 typedef void (*grpc_ioreq_completion_func)(grpc_call* call, int success, 56 void* user_data); 57 58 typedef struct grpc_call_create_args { 59 grpc_core::RefCountedPtr<grpc_core::Channel> channel; 60 grpc_core::Server* server; 61 62 grpc_call* parent; 63 uint32_t propagation_mask; 64 65 grpc_completion_queue* cq; 66 // if not NULL, it'll be used in lieu of cq 67 grpc_pollset_set* pollset_set_alternative; 68 69 const void* server_transport_data; 70 71 absl::optional<grpc_core::Slice> path; 72 absl::optional<grpc_core::Slice> authority; 73 74 grpc_core::Timestamp send_deadline; 75 } grpc_call_create_args; 76 77 namespace grpc_core { 78 class PromiseBasedCall; 79 class ServerPromiseBasedCall; 80 81 class ServerCallContext { 82 public: ServerCallContext(ServerPromiseBasedCall * call,const void * server_stream_data)83 ServerCallContext(ServerPromiseBasedCall* call, 84 const void* server_stream_data) 85 : call_(call), server_stream_data_(server_stream_data) {} 86 ArenaPromise<ServerMetadataHandle> MakeTopOfServerCallPromise( 87 CallArgs call_args, grpc_completion_queue* cq, 88 grpc_metadata_array* publish_initial_metadata, 89 absl::FunctionRef<void(grpc_call* call)> publish); 90 91 // Server stream data as supplied by the transport (so we can link the 92 // transport stream up with the call again). 93 // TODO(ctiller): legacy API - once we move transports to promises we'll 94 // create the promise directly and not need to pass around this token. server_stream_data()95 const void* server_stream_data() { return server_stream_data_; } 96 97 private: 98 ServerPromiseBasedCall* const call_; 99 const void* const server_stream_data_; 100 }; 101 102 // TODO(ctiller): move more call things into this type 103 class CallContext { 104 public: CallContext(PromiseBasedCall * call)105 explicit CallContext(PromiseBasedCall* call) : call_(call) {} 106 107 // Update the deadline (if deadline < the current deadline). 108 void UpdateDeadline(Timestamp deadline); 109 Timestamp deadline() const; 110 111 // Run some action in the call activity context. This is needed to adapt some 112 // legacy systems to promises, and will likely disappear once that conversion 113 // is complete. 114 void RunInContext(absl::AnyInvocable<void()> fn); 115 116 // TODO(ctiller): remove this once transport APIs are promise based 117 void IncrementRefCount(const char* reason = "call_context"); 118 119 // TODO(ctiller): remove this once transport APIs are promise based 120 void Unref(const char* reason = "call_context"); 121 Ref()122 RefCountedPtr<CallContext> Ref() { 123 IncrementRefCount(); 124 return RefCountedPtr<CallContext>(this); 125 } 126 call_stats()127 grpc_call_stats* call_stats() { return &call_stats_; } 128 gpr_atm* peer_string_atm_ptr(); 129 130 ServerCallContext* server_call_context(); 131 set_traced(bool traced)132 void set_traced(bool traced) { traced_ = traced; } traced()133 bool traced() const { return traced_; } 134 135 private: 136 friend class PromiseBasedCall; 137 // Call final info. 138 grpc_call_stats call_stats_; 139 // TODO(ctiller): remove this once transport APIs are promise based and we 140 // don't need refcounting here. 141 PromiseBasedCall* const call_; 142 // Is this call traced? 143 bool traced_ = false; 144 }; 145 146 template <> 147 struct ContextType<CallContext> {}; 148 149 } // namespace grpc_core 150 151 // Create a new call based on \a args. 152 // Regardless of success or failure, always returns a valid new call into *call 153 // 154 grpc_error_handle grpc_call_create(grpc_call_create_args* args, 155 grpc_call** call); 156 157 void grpc_call_set_completion_queue(grpc_call* call, grpc_completion_queue* cq); 158 159 grpc_core::Arena* grpc_call_get_arena(grpc_call* call); 160 161 grpc_call_stack* grpc_call_get_call_stack(grpc_call* call); 162 163 grpc_call_error grpc_call_start_batch_and_execute(grpc_call* call, 164 const grpc_op* ops, 165 size_t nops, 166 grpc_closure* closure); 167 168 // gRPC core internal version of grpc_call_cancel that does not create 169 // exec_ctx. 170 void grpc_call_cancel_internal(grpc_call* call); 171 172 // Given the top call_element, get the call object. 173 grpc_call* grpc_call_from_top_element(grpc_call_element* surface_element); 174 175 void grpc_call_log_batch(const char* file, int line, gpr_log_severity severity, 176 const grpc_op* ops, size_t nops); 177 178 // Set a context pointer. 179 // No thread safety guarantees are made wrt this value. 180 // TODO(#9731): add exec_ctx to destroy 181 void grpc_call_context_set(grpc_call* call, grpc_context_index elem, 182 void* value, void (*destroy)(void* value)); 183 // Get a context pointer. 184 void* grpc_call_context_get(grpc_call* call, grpc_context_index elem); 185 186 #define GRPC_CALL_LOG_BATCH(sev, ops, nops) \ 187 do { \ 188 if (GRPC_TRACE_FLAG_ENABLED(grpc_api_trace)) { \ 189 grpc_call_log_batch(sev, ops, nops); \ 190 } \ 191 } while (0) 192 193 uint8_t grpc_call_is_client(grpc_call* call); 194 195 // Get the estimated memory size for a call BESIDES the call stack. Combined 196 // with the size of the call stack, it helps estimate the arena size for the 197 // initial call. 198 size_t grpc_call_get_initial_size_estimate(); 199 200 // Return an appropriate compression algorithm for the requested compression \a 201 // level in the context of \a call. 202 grpc_compression_algorithm grpc_call_compression_for_level( 203 grpc_call* call, grpc_compression_level level); 204 205 // Did this client call receive a trailers-only response 206 // TODO(markdroth): This is currently available only to the C++ API. 207 // Move to surface API if requested by other languages. 208 bool grpc_call_is_trailers_only(const grpc_call* call); 209 210 // Returns the authority for the call, as seen on the server side. 211 absl::string_view grpc_call_server_authority(const grpc_call* call); 212 213 extern grpc_core::TraceFlag grpc_call_error_trace; 214 extern grpc_core::TraceFlag grpc_compression_trace; 215 216 #endif // GRPC_SRC_CORE_LIB_SURFACE_CALL_H 217