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_CORE_LIB_CHANNEL_CHANNEL_STACK_H 20 #define GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_H 21 22 ////////////////////////////////////////////////////////////////////////////// 23 // IMPORTANT NOTE: 24 // 25 // When you update this API, please make the corresponding changes to 26 // the C++ API in src/cpp/common/channel_filter.{h,cc} 27 ////////////////////////////////////////////////////////////////////////////// 28 29 /* A channel filter defines how operations on a channel are implemented. 30 Channel filters are chained together to create full channels, and if those 31 chains are linear, then channel stacks provide a mechanism to minimize 32 allocations for that chain. 33 Call stacks are created by channel stacks and represent the per-call data 34 for that stack. */ 35 36 #include <grpc/support/port_platform.h> 37 38 #include <stddef.h> 39 40 #include <grpc/grpc.h> 41 #include <grpc/support/log.h> 42 #include <grpc/support/time.h> 43 44 #include "src/core/lib/debug/trace.h" 45 #include "src/core/lib/gpr/arena.h" 46 #include "src/core/lib/iomgr/call_combiner.h" 47 #include "src/core/lib/iomgr/polling_entity.h" 48 #include "src/core/lib/transport/transport.h" 49 50 typedef struct grpc_channel_element grpc_channel_element; 51 typedef struct grpc_call_element grpc_call_element; 52 53 typedef struct grpc_channel_stack grpc_channel_stack; 54 typedef struct grpc_call_stack grpc_call_stack; 55 56 typedef struct { 57 grpc_channel_stack* channel_stack; 58 const grpc_channel_args* channel_args; 59 /** Transport, iff it is known */ 60 grpc_transport* optional_transport; 61 int is_first; 62 int is_last; 63 } grpc_channel_element_args; 64 65 typedef struct { 66 grpc_call_stack* call_stack; 67 const void* server_transport_data; 68 grpc_call_context_element* context; 69 grpc_slice path; 70 gpr_timespec start_time; 71 grpc_millis deadline; 72 gpr_arena* arena; 73 grpc_call_combiner* call_combiner; 74 } grpc_call_element_args; 75 76 typedef struct { 77 grpc_transport_stream_stats transport_stream_stats; 78 gpr_timespec latency; /* From call creating to enqueing of received status */ 79 } grpc_call_stats; 80 81 /** Information about the call upon completion. */ 82 typedef struct { 83 grpc_call_stats stats; 84 grpc_status_code final_status; 85 const char* error_string; 86 } grpc_call_final_info; 87 88 /* Channel filters specify: 89 1. the amount of memory needed in the channel & call (via the sizeof_XXX 90 members) 91 2. functions to initialize and destroy channel & call data 92 (init_XXX, destroy_XXX) 93 3. functions to implement call operations and channel operations (call_op, 94 channel_op) 95 4. a name, which is useful when debugging 96 97 Members are laid out in approximate frequency of use order. */ 98 typedef struct { 99 /* Called to eg. send/receive data on a call. 100 See grpc_call_next_op on how to call the next element in the stack */ 101 void (*start_transport_stream_op_batch)(grpc_call_element* elem, 102 grpc_transport_stream_op_batch* op); 103 /* Called to handle channel level operations - e.g. new calls, or transport 104 closure. 105 See grpc_channel_next_op on how to call the next element in the stack */ 106 void (*start_transport_op)(grpc_channel_element* elem, grpc_transport_op* op); 107 108 /* sizeof(per call data) */ 109 size_t sizeof_call_data; 110 /* Initialize per call data. 111 elem is initialized at the start of the call, and elem->call_data is what 112 needs initializing. 113 The filter does not need to do any chaining. 114 server_transport_data is an opaque pointer. If it is NULL, this call is 115 on a client; if it is non-NULL, then it points to memory owned by the 116 transport and is on the server. Most filters want to ignore this 117 argument. 118 Implementations may assume that elem->call_data is all zeros. */ 119 grpc_error* (*init_call_elem)(grpc_call_element* elem, 120 const grpc_call_element_args* args); 121 void (*set_pollset_or_pollset_set)(grpc_call_element* elem, 122 grpc_polling_entity* pollent); 123 /* Destroy per call data. 124 The filter does not need to do any chaining. 125 The bottom filter of a stack will be passed a non-NULL pointer to 126 \a then_schedule_closure that should be passed to GRPC_CLOSURE_SCHED when 127 destruction is complete. \a final_info contains data about the completed 128 call, mainly for reporting purposes. */ 129 void (*destroy_call_elem)(grpc_call_element* elem, 130 const grpc_call_final_info* final_info, 131 grpc_closure* then_schedule_closure); 132 133 /* sizeof(per channel data) */ 134 size_t sizeof_channel_data; 135 /* Initialize per-channel data. 136 elem is initialized at the creating of the channel, and elem->channel_data 137 is what needs initializing. 138 is_first, is_last designate this elements position in the stack, and are 139 useful for asserting correct configuration by upper layer code. 140 The filter does not need to do any chaining. 141 Implementations may assume that elem->channel_data is all zeros. */ 142 grpc_error* (*init_channel_elem)(grpc_channel_element* elem, 143 grpc_channel_element_args* args); 144 /* Destroy per channel data. 145 The filter does not need to do any chaining */ 146 void (*destroy_channel_elem)(grpc_channel_element* elem); 147 148 /* Implement grpc_channel_get_info() */ 149 void (*get_channel_info)(grpc_channel_element* elem, 150 const grpc_channel_info* channel_info); 151 152 /* The name of this filter */ 153 const char* name; 154 } grpc_channel_filter; 155 156 /* A channel_element tracks its filter and the filter requested memory within 157 a channel allocation */ 158 struct grpc_channel_element { 159 const grpc_channel_filter* filter; 160 void* channel_data; 161 }; 162 163 /* A call_element tracks its filter, the filter requested memory within 164 a channel allocation, and the filter requested memory within a call 165 allocation */ 166 struct grpc_call_element { 167 const grpc_channel_filter* filter; 168 void* channel_data; 169 void* call_data; 170 }; 171 172 /* A channel stack tracks a set of related filters for one channel, and 173 guarantees they live within a single malloc() allocation */ 174 struct grpc_channel_stack { 175 grpc_stream_refcount refcount; 176 size_t count; 177 /* Memory required for a call stack (computed at channel stack 178 initialization) */ 179 size_t call_stack_size; 180 }; 181 182 /* A call stack tracks a set of related filters for one call, and guarantees 183 they live within a single malloc() allocation */ 184 struct grpc_call_stack { 185 /* shared refcount for this channel stack. 186 MUST be the first element: the underlying code calls destroy 187 with the address of the refcount, but higher layers prefer to think 188 about the address of the call stack itself. */ 189 grpc_stream_refcount refcount; 190 size_t count; 191 }; 192 193 /* Get a channel element given a channel stack and its index */ 194 grpc_channel_element* grpc_channel_stack_element(grpc_channel_stack* stack, 195 size_t i); 196 /* Get the last channel element in a channel stack */ 197 grpc_channel_element* grpc_channel_stack_last_element( 198 grpc_channel_stack* stack); 199 /* Get a call stack element given a call stack and an index */ 200 grpc_call_element* grpc_call_stack_element(grpc_call_stack* stack, size_t i); 201 202 /* Determine memory required for a channel stack containing a set of filters */ 203 size_t grpc_channel_stack_size(const grpc_channel_filter** filters, 204 size_t filter_count); 205 /* Initialize a channel stack given some filters */ 206 grpc_error* grpc_channel_stack_init( 207 int initial_refs, grpc_iomgr_cb_func destroy, void* destroy_arg, 208 const grpc_channel_filter** filters, size_t filter_count, 209 const grpc_channel_args* args, grpc_transport* optional_transport, 210 const char* name, grpc_channel_stack* stack); 211 /* Destroy a channel stack */ 212 void grpc_channel_stack_destroy(grpc_channel_stack* stack); 213 214 /* Initialize a call stack given a channel stack. transport_server_data is 215 expected to be NULL on a client, or an opaque transport owned pointer on the 216 server. */ 217 grpc_error* grpc_call_stack_init(grpc_channel_stack* channel_stack, 218 int initial_refs, grpc_iomgr_cb_func destroy, 219 void* destroy_arg, 220 const grpc_call_element_args* elem_args); 221 /* Set a pollset or a pollset_set for a call stack: must occur before the first 222 * op is started */ 223 void grpc_call_stack_set_pollset_or_pollset_set(grpc_call_stack* call_stack, 224 grpc_polling_entity* pollent); 225 226 #ifndef NDEBUG 227 #define GRPC_CALL_STACK_REF(call_stack, reason) \ 228 grpc_stream_ref(&(call_stack)->refcount, reason) 229 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \ 230 grpc_stream_unref(&(call_stack)->refcount, reason) 231 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \ 232 grpc_stream_ref(&(channel_stack)->refcount, reason) 233 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \ 234 grpc_stream_unref(&(channel_stack)->refcount, reason) 235 #else 236 #define GRPC_CALL_STACK_REF(call_stack, reason) \ 237 grpc_stream_ref(&(call_stack)->refcount) 238 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \ 239 grpc_stream_unref(&(call_stack)->refcount) 240 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \ 241 grpc_stream_ref(&(channel_stack)->refcount) 242 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \ 243 grpc_stream_unref(&(channel_stack)->refcount) 244 #endif 245 246 /* Destroy a call stack */ 247 void grpc_call_stack_destroy(grpc_call_stack* stack, 248 const grpc_call_final_info* final_info, 249 grpc_closure* then_schedule_closure); 250 251 /* Ignore set pollset{_set} - used by filters if they don't care about pollsets 252 * at all. Does nothing. */ 253 void grpc_call_stack_ignore_set_pollset_or_pollset_set( 254 grpc_call_element* elem, grpc_polling_entity* pollent); 255 /* Call the next operation in a call stack */ 256 void grpc_call_next_op(grpc_call_element* elem, 257 grpc_transport_stream_op_batch* op); 258 /* Call the next operation (depending on call directionality) in a channel 259 stack */ 260 void grpc_channel_next_op(grpc_channel_element* elem, grpc_transport_op* op); 261 /* Pass through a request to get_channel_info() to the next child element */ 262 void grpc_channel_next_get_info(grpc_channel_element* elem, 263 const grpc_channel_info* channel_info); 264 265 /* Given the top element of a channel stack, get the channel stack itself */ 266 grpc_channel_stack* grpc_channel_stack_from_top_element( 267 grpc_channel_element* elem); 268 /* Given the top element of a call stack, get the call stack itself */ 269 grpc_call_stack* grpc_call_stack_from_top_element(grpc_call_element* elem); 270 271 void grpc_call_log_op(const char* file, int line, gpr_log_severity severity, 272 grpc_call_element* elem, 273 grpc_transport_stream_op_batch* op); 274 275 extern grpc_core::TraceFlag grpc_trace_channel; 276 277 #define GRPC_CALL_LOG_OP(sev, elem, op) \ 278 if (grpc_trace_channel.enabled()) grpc_call_log_op(sev, elem, op) 279 280 #endif /* GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_H */ 281