GRPC Core  18.0.0
channel_stack.h
Go to the documentation of this file.
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 
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}
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  Implementations should take care of the following details for a batch -
37  1. Synchronization is achieved with a CallCombiner. View
38  src/core/lib/iomgr/call_combiner.h for more details.
39  2. If the filter wants to inject an error on the way down, it needs to call
40  grpc_transport_stream_op_batch_finish_with_failure from within the call
41  combiner. This will cause any batch callbacks to be called with that error.
42  3. If the filter wants to inject an error on the way up (from a callback), it
43  should also inject that error in the recv_trailing_metadata callback so that
44  it can have an effect on the call status.
45 */
46 
48 
49 #include <stddef.h>
50 
51 #include <grpc/grpc.h>
52 #include <grpc/support/log.h>
53 #include <grpc/support/time.h>
54 
61 
64 
66 typedef struct grpc_call_stack grpc_call_stack;
67 
73  int is_first;
74  int is_last;
75 };
78  const void* server_transport_data;
80  const grpc_slice& path;
81  gpr_cycle_counter start_time;
85 };
88  gpr_timespec latency; /* From call creating to enqueing of received status */
89 };
94  const char* error_string = nullptr;
95 };
96 
97 /* Channel filters specify:
98  1. the amount of memory needed in the channel & call (via the sizeof_XXX
99  members)
100  2. functions to initialize and destroy channel & call data
101  (init_XXX, destroy_XXX)
102  3. functions to implement call operations and channel operations (call_op,
103  channel_op)
104  4. a name, which is useful when debugging
105 
106  Members are laid out in approximate frequency of use order. */
108  /* Called to eg. send/receive data on a call.
109  See grpc_call_next_op on how to call the next element in the stack */
112  /* Called to handle channel level operations - e.g. new calls, or transport
113  closure.
114  See grpc_channel_next_op on how to call the next element in the stack */
116 
117  /* sizeof(per call data) */
119  /* Initialize per call data.
120  elem is initialized at the start of the call, and elem->call_data is what
121  needs initializing.
122  The filter does not need to do any chaining.
123  server_transport_data is an opaque pointer. If it is NULL, this call is
124  on a client; if it is non-NULL, then it points to memory owned by the
125  transport and is on the server. Most filters want to ignore this
126  argument.
127  Implementations may assume that elem->call_data is all zeros. */
129  const grpc_call_element_args* args);
131  grpc_polling_entity* pollent);
132  /* Destroy per call data.
133  The filter does not need to do any chaining.
134  The bottom filter of a stack will be passed a non-NULL pointer to
135  \a then_schedule_closure that should be passed to GRPC_CLOSURE_SCHED when
136  destruction is complete. \a final_info contains data about the completed
137  call, mainly for reporting purposes. */
139  const grpc_call_final_info* final_info,
140  grpc_closure* then_schedule_closure);
141 
142  /* sizeof(per channel data) */
144  /* Initialize per-channel data.
145  elem is initialized at the creating of the channel, and elem->channel_data
146  is what needs initializing.
147  is_first, is_last designate this elements position in the stack, and are
148  useful for asserting correct configuration by upper layer code.
149  The filter does not need to do any chaining.
150  Implementations may assume that elem->channel_data is all zeros. */
153  /* Destroy per channel data.
154  The filter does not need to do any chaining */
156 
157  /* Implement grpc_channel_get_info() */
159  const grpc_channel_info* channel_info);
160 
161  /* The name of this filter */
162  const char* name;
163 };
164 /* A channel_element tracks its filter and the filter requested memory within
165  a channel allocation */
169 };
170 
171 /* A call_element tracks its filter, the filter requested memory within
172  a channel allocation, and the filter requested memory within a call
173  allocation */
177  void* call_data;
178 };
179 
180 /* A channel stack tracks a set of related filters for one channel, and
181  guarantees they live within a single malloc() allocation */
184  size_t count;
185  /* Memory required for a call stack (computed at channel stack
186  initialization) */
188 };
189 
190 /* A call stack tracks a set of related filters for one call, and guarantees
191  they live within a single malloc() allocation */
193  /* shared refcount for this channel stack.
194  MUST be the first element: the underlying code calls destroy
195  with the address of the refcount, but higher layers prefer to think
196  about the address of the call stack itself. */
198  size_t count;
199 };
200 
201 /* Get a channel element given a channel stack and its index */
203  size_t i);
204 /* Get the last channel element in a channel stack */
206  grpc_channel_stack* stack);
207 
208 // A utility function for a filter to determine how many other instances
209 // of the same filter exist above it in the same stack. Intended to be
210 // used in the filter's init_channel_elem() method.
212  grpc_channel_stack* channel_stack, grpc_channel_element* elem);
213 
214 /* Get a call stack element given a call stack and an index */
216 
217 /* Determine memory required for a channel stack containing a set of filters */
218 size_t grpc_channel_stack_size(const grpc_channel_filter** filters,
219  size_t filter_count);
220 /* Initialize a channel stack given some filters */
222  int initial_refs, grpc_iomgr_cb_func destroy, void* destroy_arg,
223  const grpc_channel_filter** filters, size_t filter_count,
224  const grpc_channel_args* args, grpc_transport* optional_transport,
225  const char* name, grpc_channel_stack* stack);
226 /* Destroy a channel stack */
228 
229 /* Initialize a call stack given a channel stack. transport_server_data is
230  expected to be NULL on a client, or an opaque transport owned pointer on the
231  server. */
233  int initial_refs,
234  grpc_iomgr_cb_func destroy,
235  void* destroy_arg,
236  const grpc_call_element_args* elem_args);
237 /* Set a pollset or a pollset_set for a call stack: must occur before the first
238  * op is started */
240  grpc_polling_entity* pollent);
241 
242 #ifndef NDEBUG
243 #define GRPC_CALL_STACK_REF(call_stack, reason) \
244  grpc_stream_ref(&(call_stack)->refcount, reason)
245 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \
246  grpc_stream_unref(&(call_stack)->refcount, reason)
247 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \
248  grpc_stream_ref(&(channel_stack)->refcount, reason)
249 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \
250  grpc_stream_unref(&(channel_stack)->refcount, reason)
251 #else
252 #define GRPC_CALL_STACK_REF(call_stack, reason) \
253  do { \
254  grpc_stream_ref(&(call_stack)->refcount); \
255  (void)(reason); \
256  } while (0);
257 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \
258  do { \
259  grpc_stream_unref(&(call_stack)->refcount); \
260  (void)(reason); \
261  } while (0);
262 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \
263  do { \
264  grpc_stream_ref(&(channel_stack)->refcount); \
265  (void)(reason); \
266  } while (0);
267 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \
268  do { \
269  grpc_stream_unref(&(channel_stack)->refcount); \
270  (void)(reason); \
271  } while (0);
272 #endif
273 
274 /* Destroy a call stack */
276  const grpc_call_final_info* final_info,
277  grpc_closure* then_schedule_closure);
278 
279 /* Ignore set pollset{_set} - used by filters if they don't care about pollsets
280  * at all. Does nothing. */
282  grpc_call_element* elem, grpc_polling_entity* pollent);
283 /* Call the next operation in a call stack */
286 /* Call the next operation (depending on call directionality) in a channel
287  stack */
289 /* Pass through a request to get_channel_info() to the next child element */
291  const grpc_channel_info* channel_info);
292 
293 /* Given the top element of a channel stack, get the channel stack itself */
295  grpc_channel_element* elem);
296 /* Given the top element of a call stack, get the call stack itself */
298 
299 void grpc_call_log_op(const char* file, int line, gpr_log_severity severity,
300  grpc_call_element* elem,
302 
304 
305 #define GRPC_CALL_LOG_OP(sev, elem, op) \
306  do { \
307  if (GRPC_TRACE_FLAG_ENABLED(grpc_trace_channel)) { \
308  grpc_call_log_op(sev, elem, op); \
309  } \
310  } while (0)
311 
312 #endif /* GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_H */
void grpc_channel_next_get_info(grpc_channel_element *elem, const grpc_channel_info *channel_info)
Definition: channel_stack.cc:243
grpc_channel_element * grpc_channel_stack_last_element(grpc_channel_stack *stack)
Definition: channel_stack.cc:79
grpc_error_handle grpc_channel_stack_init(int initial_refs, grpc_iomgr_cb_func destroy, void *destroy_arg, const grpc_channel_filter **filters, size_t filter_count, const grpc_channel_args *args, grpc_transport *optional_transport, const char *name, grpc_channel_stack *stack)
Definition: channel_stack.cc:101
grpc_channel_stack * grpc_channel_stack_from_top_element(grpc_channel_element *elem)
Definition: channel_stack.cc:254
void grpc_call_stack_set_pollset_or_pollset_set(grpc_call_stack *call_stack, grpc_polling_entity *pollent)
Definition: channel_stack.cc:204
size_t grpc_channel_stack_size(const grpc_channel_filter **filters, size_t filter_count)
Definition: channel_stack.cc:47
void grpc_call_stack_ignore_set_pollset_or_pollset_set(grpc_call_element *elem, grpc_polling_entity *pollent)
Definition: channel_stack.cc:218
grpc_channel_element * grpc_channel_stack_element(grpc_channel_stack *stack, size_t i)
Definition: channel_stack.cc:74
grpc_call_stack * grpc_call_stack_from_top_element(grpc_call_element *elem)
Definition: channel_stack.cc:261
grpc_core::TraceFlag grpc_trace_channel
void grpc_call_next_op(grpc_call_element *elem, grpc_transport_stream_op_batch *op)
Definition: channel_stack.cc:236
size_t grpc_channel_stack_filter_instance_number(grpc_channel_stack *channel_stack, grpc_channel_element *elem)
Definition: channel_stack.cc:84
grpc_error_handle grpc_call_stack_init(grpc_channel_stack *channel_stack, int initial_refs, grpc_iomgr_cb_func destroy, void *destroy_arg, const grpc_call_element_args *elem_args)
Definition: channel_stack.cc:165
void grpc_channel_stack_destroy(grpc_channel_stack *stack)
Definition: channel_stack.cc:154
grpc_call_element * grpc_call_stack_element(grpc_call_stack *stack, size_t i)
Definition: channel_stack.cc:96
void grpc_call_stack_destroy(grpc_call_stack *stack, const grpc_call_final_info *final_info, grpc_closure *then_schedule_closure)
Definition: channel_stack.cc:221
void grpc_channel_next_op(grpc_channel_element *elem, grpc_transport_op *op)
Definition: channel_stack.cc:249
void grpc_call_log_op(const char *file, int line, gpr_log_severity severity, grpc_call_element *elem, grpc_transport_stream_op_batch *op)
Definition: transport_op_string.cc:164
Definition: arena.h:44
Definition: call_combiner.h:50
Definition: trace.h:61
void(* grpc_iomgr_cb_func)(void *arg, grpc_error_handle error)
gRPC Callback definition.
Definition: closure.h:53
grpc_error * grpc_error_handle
Definition: error.h:48
int64_t grpc_millis
Definition: exec_ctx.h:37
gpr_log_severity
GPR log API.
Definition: log.h:43
grpc_status_code
Definition: status.h:26
@ GRPC_STATUS_OK
Not an error; returned on success.
Definition: status.h:28
Analogous to struct timespec.
Definition: gpr_types.h:47
Definition: context.h:44
Definition: channel_stack.h:76
grpc_core::Arena * arena
Definition: channel_stack.h:83
gpr_cycle_counter start_time
Definition: channel_stack.h:81
grpc_call_stack * call_stack
Definition: channel_stack.h:77
const void * server_transport_data
Definition: channel_stack.h:78
grpc_call_context_element * context
Definition: channel_stack.h:79
grpc_millis deadline
Definition: channel_stack.h:82
grpc_core::CallCombiner * call_combiner
Definition: channel_stack.h:84
const grpc_slice & path
Definition: channel_stack.h:80
Definition: channel_stack.h:174
void * call_data
Definition: channel_stack.h:177
const grpc_channel_filter * filter
Definition: channel_stack.h:175
void * channel_data
Definition: channel_stack.h:176
Information about the call upon completion.
Definition: channel_stack.h:91
grpc_status_code final_status
Definition: channel_stack.h:93
grpc_call_stats stats
Definition: channel_stack.h:92
const char * error_string
Definition: channel_stack.h:94
Definition: channel_stack.h:192
size_t count
Definition: channel_stack.h:198
grpc_stream_refcount refcount
Definition: channel_stack.h:197
Definition: channel_stack.h:86
gpr_timespec latency
Definition: channel_stack.h:88
grpc_transport_stream_stats transport_stream_stats
Definition: channel_stack.h:87
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: channel_stack.h:68
const grpc_channel_args * channel_args
Definition: channel_stack.h:70
int is_first
Definition: channel_stack.h:73
int is_last
Definition: channel_stack.h:74
grpc_channel_stack * channel_stack
Definition: channel_stack.h:69
grpc_transport * optional_transport
Transport, iff it is known.
Definition: channel_stack.h:72
Definition: channel_stack.h:166
const grpc_channel_filter * filter
Definition: channel_stack.h:167
void * channel_data
Definition: channel_stack.h:168
Definition: channel_stack.h:107
void(* destroy_call_elem)(grpc_call_element *elem, const grpc_call_final_info *final_info, grpc_closure *then_schedule_closure)
Definition: channel_stack.h:138
void(* start_transport_op)(grpc_channel_element *elem, grpc_transport_op *op)
Definition: channel_stack.h:115
grpc_error_handle(* init_channel_elem)(grpc_channel_element *elem, grpc_channel_element_args *args)
Definition: channel_stack.h:151
void(* set_pollset_or_pollset_set)(grpc_call_element *elem, grpc_polling_entity *pollent)
Definition: channel_stack.h:130
grpc_error_handle(* init_call_elem)(grpc_call_element *elem, const grpc_call_element_args *args)
Definition: channel_stack.h:128
void(* start_transport_stream_op_batch)(grpc_call_element *elem, grpc_transport_stream_op_batch *op)
Definition: channel_stack.h:110
void(* get_channel_info)(grpc_channel_element *elem, const grpc_channel_info *channel_info)
Definition: channel_stack.h:158
size_t sizeof_channel_data
Definition: channel_stack.h:143
void(* destroy_channel_elem)(grpc_channel_element *elem)
Definition: channel_stack.h:155
const char * name
Definition: channel_stack.h:162
size_t sizeof_call_data
Definition: channel_stack.h:118
Information requested from the channel.
Definition: grpc_types.h:704
Definition: channel_stack.h:182
size_t call_stack_size
Definition: channel_stack.h:187
grpc_stream_refcount refcount
Definition: channel_stack.h:183
size_t count
Definition: channel_stack.h:184
A closure over a grpc_iomgr_cb_func.
Definition: closure.h:56
Definition: error_internal.h:41
Definition: polling_entity.h:37
A grpc_slice s, if initialized, represents the byte range s.bytes[0..s.length-1].
Definition: slice.h:60
Definition: transport.h:56
Transport op: a set of operations to perform on a transport as a whole.
Definition: transport.h:332
Definition: transport.h:163
Definition: transport.h:128
Definition: transport_impl.h:66