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/gpr/time_precise.h" 42 #include "src/core/lib/gprpp/ref_counted_ptr.h" 43 #include "src/core/lib/gprpp/time.h" 44 #include "src/core/lib/iomgr/closure.h" 45 #include "src/core/lib/iomgr/error.h" 46 #include "src/core/lib/iomgr/iomgr_fwd.h" 47 #include "src/core/lib/promise/arena_promise.h" 48 #include "src/core/lib/promise/context.h" 49 #include "src/core/lib/resource_quota/arena.h" 50 #include "src/core/lib/slice/slice.h" 51 #include "src/core/lib/surface/api_trace.h" 52 #include "src/core/lib/surface/channel.h" 53 #include "src/core/lib/surface/server_interface.h" 54 #include "src/core/lib/transport/transport.h" 55 56 typedef void (*grpc_ioreq_completion_func)(grpc_call* call, int success, 57 void* user_data); 58 59 typedef struct grpc_call_create_args { 60 grpc_core::RefCountedPtr<grpc_core::Channel> channel; 61 grpc_core::ServerInterface* server; 62 63 grpc_call* parent; 64 uint32_t propagation_mask; 65 66 grpc_completion_queue* cq; 67 // if not NULL, it'll be used in lieu of cq 68 grpc_pollset_set* pollset_set_alternative; 69 70 const void* server_transport_data; 71 72 absl::optional<grpc_core::Slice> path; 73 absl::optional<grpc_core::Slice> authority; 74 75 grpc_core::Timestamp send_deadline; 76 bool registered_method; // client_only 77 } grpc_call_create_args; 78 79 namespace grpc_core { 80 class BasicPromiseBasedCall; 81 class ServerPromiseBasedCall; 82 83 class ServerCallContext { 84 public: 85 virtual void PublishInitialMetadata( 86 ClientMetadataHandle metadata, 87 grpc_metadata_array* publish_initial_metadata) = 0; 88 89 // Construct the top of the server call promise for the v2 filter stack. 90 // TODO(ctiller): delete when v3 is available. 91 virtual ArenaPromise<ServerMetadataHandle> MakeTopOfServerCallPromise( 92 CallArgs call_args, grpc_completion_queue* cq, 93 absl::FunctionRef<void(grpc_call* call)> publish) = 0; 94 95 // Server stream data as supplied by the transport (so we can link the 96 // transport stream up with the call again). 97 // TODO(ctiller): legacy API - once we move transports to promises we'll 98 // create the promise directly and not need to pass around this token. 99 virtual const void* server_stream_data() = 0; 100 101 protected: 102 ~ServerCallContext() = default; 103 }; 104 105 // TODO(ctiller): move more call things into this type 106 class CallContext { 107 public: CallContext(BasicPromiseBasedCall * call)108 explicit CallContext(BasicPromiseBasedCall* call) : call_(call) {} 109 110 // Update the deadline (if deadline < the current deadline). 111 void UpdateDeadline(Timestamp deadline); 112 Timestamp deadline() const; 113 114 // Run some action in the call activity context. This is needed to adapt some 115 // legacy systems to promises, and will likely disappear once that conversion 116 // is complete. 117 void RunInContext(absl::AnyInvocable<void()> fn); 118 119 // TODO(ctiller): remove this once transport APIs are promise based 120 void IncrementRefCount(const char* reason = "call_context"); 121 122 // TODO(ctiller): remove this once transport APIs are promise based 123 void Unref(const char* reason = "call_context"); 124 Ref()125 RefCountedPtr<CallContext> Ref() { 126 IncrementRefCount(); 127 return RefCountedPtr<CallContext>(this); 128 } 129 call_stats()130 grpc_call_stats* call_stats() { return &call_stats_; } 131 gpr_atm* peer_string_atm_ptr(); call_start_time()132 gpr_cycle_counter call_start_time() { return start_time_; } 133 134 ServerCallContext* server_call_context(); 135 set_traced(bool traced)136 void set_traced(bool traced) { traced_ = traced; } traced()137 bool traced() const { return traced_; } 138 139 // TEMPORARY HACK 140 // Create a call spine object for this call. 141 // Said object should only be created once. 142 // Allows interop between the v2 call stack and the v3 (which is required by 143 // transports). 144 RefCountedPtr<CallSpineInterface> MakeCallSpine(CallArgs call_args); 145 grpc_call* c_call(); 146 147 private: 148 friend class PromiseBasedCall; 149 // Call final info. 150 grpc_call_stats call_stats_; 151 // TODO(ctiller): remove this once transport APIs are promise based and we 152 // don't need refcounting here. 153 BasicPromiseBasedCall* const call_; 154 gpr_cycle_counter start_time_ = gpr_get_cycle_counter(); 155 // Is this call traced? 156 bool traced_ = false; 157 }; 158 159 template <> 160 struct ContextType<CallContext> {}; 161 162 RefCountedPtr<CallSpineInterface> MakeServerCall(ServerInterface* server, 163 Channel* channel, 164 Arena* arena); 165 166 } // namespace grpc_core 167 168 // Create a new call based on \a args. 169 // Regardless of success or failure, always returns a valid new call into *call 170 // 171 grpc_error_handle grpc_call_create(grpc_call_create_args* args, 172 grpc_call** call); 173 174 void grpc_call_set_completion_queue(grpc_call* call, grpc_completion_queue* cq); 175 176 grpc_core::Arena* grpc_call_get_arena(grpc_call* call); 177 178 grpc_call_stack* grpc_call_get_call_stack(grpc_call* call); 179 180 grpc_call_error grpc_call_start_batch_and_execute(grpc_call* call, 181 const grpc_op* ops, 182 size_t nops, 183 grpc_closure* closure); 184 185 // gRPC core internal version of grpc_call_cancel that does not create 186 // exec_ctx. 187 void grpc_call_cancel_internal(grpc_call* call); 188 189 // Given the top call_element, get the call object. 190 grpc_call* grpc_call_from_top_element(grpc_call_element* surface_element); 191 192 void grpc_call_log_batch(const char* file, int line, gpr_log_severity severity, 193 const grpc_op* ops, size_t nops); 194 195 // Set a context pointer. 196 // No thread safety guarantees are made wrt this value. 197 // TODO(#9731): add exec_ctx to destroy 198 void grpc_call_context_set(grpc_call* call, grpc_context_index elem, 199 void* value, void (*destroy)(void* value)); 200 // Get a context pointer. 201 void* grpc_call_context_get(grpc_call* call, grpc_context_index elem); 202 203 #define GRPC_CALL_LOG_BATCH(sev, ops, nops) \ 204 do { \ 205 if (GRPC_TRACE_FLAG_ENABLED(grpc_api_trace)) { \ 206 grpc_call_log_batch(sev, ops, nops); \ 207 } \ 208 } while (0) 209 210 uint8_t grpc_call_is_client(grpc_call* call); 211 212 // Get the estimated memory size for a call BESIDES the call stack. Combined 213 // with the size of the call stack, it helps estimate the arena size for the 214 // initial call. 215 size_t grpc_call_get_initial_size_estimate(); 216 217 // Return an appropriate compression algorithm for the requested compression \a 218 // level in the context of \a call. 219 grpc_compression_algorithm grpc_call_compression_for_level( 220 grpc_call* call, grpc_compression_level level); 221 222 // Did this client call receive a trailers-only response 223 // TODO(markdroth): This is currently available only to the C++ API. 224 // Move to surface API if requested by other languages. 225 bool grpc_call_is_trailers_only(const grpc_call* call); 226 227 // Returns the authority for the call, as seen on the server side. 228 absl::string_view grpc_call_server_authority(const grpc_call* call); 229 230 extern grpc_core::TraceFlag grpc_call_error_trace; 231 extern grpc_core::TraceFlag grpc_compression_trace; 232 233 #endif // GRPC_SRC_CORE_LIB_SURFACE_CALL_H 234