GRPC Core  9.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 
37 
38 #include <stddef.h>
39 
40 #include <grpc/grpc.h>
41 #include <grpc/support/log.h>
42 #include <grpc/support/time.h>
43 
50 
53 
55 typedef struct grpc_call_stack grpc_call_stack;
56 
57 typedef struct {
62  int is_first;
63  int is_last;
65 
66 typedef struct {
68  const void* server_transport_data;
70  const grpc_slice& path;
71  gpr_cycle_counter start_time;
76 
77 typedef struct {
79  gpr_timespec latency; /* From call creating to enqueing of received status */
81 
86  const char* error_string = nullptr;
87 };
88 
89 /* Channel filters specify:
90  1. the amount of memory needed in the channel & call (via the sizeof_XXX
91  members)
92  2. functions to initialize and destroy channel & call data
93  (init_XXX, destroy_XXX)
94  3. functions to implement call operations and channel operations (call_op,
95  channel_op)
96  4. a name, which is useful when debugging
97 
98  Members are laid out in approximate frequency of use order. */
99 typedef struct {
100  /* Called to eg. send/receive data on a call.
101  See grpc_call_next_op on how to call the next element in the stack */
102  void (*start_transport_stream_op_batch)(grpc_call_element* elem,
104  /* Called to handle channel level operations - e.g. new calls, or transport
105  closure.
106  See grpc_channel_next_op on how to call the next element in the stack */
107  void (*start_transport_op)(grpc_channel_element* elem, grpc_transport_op* op);
108 
109  /* sizeof(per call data) */
111  /* Initialize per call data.
112  elem is initialized at the start of the call, and elem->call_data is what
113  needs initializing.
114  The filter does not need to do any chaining.
115  server_transport_data is an opaque pointer. If it is NULL, this call is
116  on a client; if it is non-NULL, then it points to memory owned by the
117  transport and is on the server. Most filters want to ignore this
118  argument.
119  Implementations may assume that elem->call_data is all zeros. */
120  grpc_error* (*init_call_elem)(grpc_call_element* elem,
121  const grpc_call_element_args* args);
122  void (*set_pollset_or_pollset_set)(grpc_call_element* elem,
123  grpc_polling_entity* pollent);
124  /* Destroy per call data.
125  The filter does not need to do any chaining.
126  The bottom filter of a stack will be passed a non-NULL pointer to
127  \a then_schedule_closure that should be passed to GRPC_CLOSURE_SCHED when
128  destruction is complete. \a final_info contains data about the completed
129  call, mainly for reporting purposes. */
130  void (*destroy_call_elem)(grpc_call_element* elem,
131  const grpc_call_final_info* final_info,
132  grpc_closure* then_schedule_closure);
133 
134  /* sizeof(per channel data) */
136  /* Initialize per-channel data.
137  elem is initialized at the creating of the channel, and elem->channel_data
138  is what needs initializing.
139  is_first, is_last designate this elements position in the stack, and are
140  useful for asserting correct configuration by upper layer code.
141  The filter does not need to do any chaining.
142  Implementations may assume that elem->channel_data is all zeros. */
143  grpc_error* (*init_channel_elem)(grpc_channel_element* elem,
145  /* Destroy per channel data.
146  The filter does not need to do any chaining */
147  void (*destroy_channel_elem)(grpc_channel_element* elem);
148 
149  /* Implement grpc_channel_get_info() */
150  void (*get_channel_info)(grpc_channel_element* elem,
151  const grpc_channel_info* channel_info);
152 
153  /* The name of this filter */
154  const char* name;
156 
157 /* A channel_element tracks its filter and the filter requested memory within
158  a channel allocation */
162 };
163 
164 /* A call_element tracks its filter, the filter requested memory within
165  a channel allocation, and the filter requested memory within a call
166  allocation */
170  void* call_data;
171 };
172 
173 /* A channel stack tracks a set of related filters for one channel, and
174  guarantees they live within a single malloc() allocation */
177  size_t count;
178  /* Memory required for a call stack (computed at channel stack
179  initialization) */
181 };
182 
183 /* A call stack tracks a set of related filters for one call, and guarantees
184  they live within a single malloc() allocation */
186  /* shared refcount for this channel stack.
187  MUST be the first element: the underlying code calls destroy
188  with the address of the refcount, but higher layers prefer to think
189  about the address of the call stack itself. */
191  size_t count;
192 };
193 
194 /* Get a channel element given a channel stack and its index */
196  size_t i);
197 /* Get the last channel element in a channel stack */
199  grpc_channel_stack* stack);
200 /* Get a call stack element given a call stack and an index */
202 
203 /* Determine memory required for a channel stack containing a set of filters */
204 size_t grpc_channel_stack_size(const grpc_channel_filter** filters,
205  size_t filter_count);
206 /* Initialize a channel stack given some filters */
208  int initial_refs, grpc_iomgr_cb_func destroy, void* destroy_arg,
209  const grpc_channel_filter** filters, size_t filter_count,
210  const grpc_channel_args* args, grpc_transport* optional_transport,
211  const char* name, grpc_channel_stack* stack);
212 /* Destroy a channel stack */
214 
215 /* Initialize a call stack given a channel stack. transport_server_data is
216  expected to be NULL on a client, or an opaque transport owned pointer on the
217  server. */
219  int initial_refs, grpc_iomgr_cb_func destroy,
220  void* destroy_arg,
221  const grpc_call_element_args* elem_args);
222 /* Set a pollset or a pollset_set for a call stack: must occur before the first
223  * op is started */
225  grpc_polling_entity* pollent);
226 
227 #ifndef NDEBUG
228 #define GRPC_CALL_STACK_REF(call_stack, reason) \
229  grpc_stream_ref(&(call_stack)->refcount, reason)
230 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \
231  grpc_stream_unref(&(call_stack)->refcount, reason)
232 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \
233  grpc_stream_ref(&(channel_stack)->refcount, reason)
234 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \
235  grpc_stream_unref(&(channel_stack)->refcount, reason)
236 #else
237 #define GRPC_CALL_STACK_REF(call_stack, reason) \
238  do { \
239  grpc_stream_ref(&(call_stack)->refcount); \
240  (void)(reason); \
241  } while (0);
242 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \
243  do { \
244  grpc_stream_unref(&(call_stack)->refcount); \
245  (void)(reason); \
246  } while (0);
247 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \
248  do { \
249  grpc_stream_ref(&(channel_stack)->refcount); \
250  (void)(reason); \
251  } while (0);
252 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \
253  do { \
254  grpc_stream_unref(&(channel_stack)->refcount); \
255  (void)(reason); \
256  } while (0);
257 #endif
258 
259 /* Destroy a call stack */
261  const grpc_call_final_info* final_info,
262  grpc_closure* then_schedule_closure);
263 
264 /* Ignore set pollset{_set} - used by filters if they don't care about pollsets
265  * at all. Does nothing. */
268 /* Call the next operation in a call stack */
271 /* Call the next operation (depending on call directionality) in a channel
272  stack */
274 /* Pass through a request to get_channel_info() to the next child element */
276  const grpc_channel_info* channel_info);
277 
278 /* Given the top element of a channel stack, get the channel stack itself */
281 /* Given the top element of a call stack, get the call stack itself */
283 
284 void grpc_call_log_op(const char* file, int line, gpr_log_severity severity,
287 
289 
290 #define GRPC_CALL_LOG_OP(sev, elem, op) \
291  do { \
292  if (GRPC_TRACE_FLAG_ENABLED(grpc_trace_channel)) { \
293  grpc_call_log_op(sev, elem, op); \
294  } \
295  } while (0)
296 
297 #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:230
grpc_channel_element * grpc_channel_stack_last_element(grpc_channel_stack *stack)
Definition: channel_stack.cc:79
grpc_channel_stack * grpc_channel_stack_from_top_element(grpc_channel_element *elem)
Definition: channel_stack.cc:241
void grpc_call_stack_set_pollset_or_pollset_set(grpc_call_stack *call_stack, grpc_polling_entity *pollent)
Definition: channel_stack.cc:191
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:205
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:248
grpc_error * 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:152
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:223
void grpc_channel_stack_destroy(grpc_channel_stack *stack)
Definition: channel_stack.cc:141
grpc_call_element * grpc_call_stack_element(grpc_call_stack *stack, size_t i)
Definition: channel_stack.cc:84
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:208
void grpc_channel_next_op(grpc_channel_element *elem, grpc_transport_op *op)
Definition: channel_stack.cc:236
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:204
grpc_error * 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:89
Definition: arena.h:44
Definition: call_combiner.h:49
Definition: trace.h:61
grpc_call_element * elem
Definition: client_channel.cc:112
void(* grpc_iomgr_cb_func)(void *arg, grpc_error *error)
gRPC Callback definition.
Definition: closure.h:53
int64_t grpc_millis
Definition: exec_ctx.h:35
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:66
grpc_core::Arena * arena
Definition: channel_stack.h:73
gpr_cycle_counter start_time
Definition: channel_stack.h:71
grpc_call_stack * call_stack
Definition: channel_stack.h:67
const void * server_transport_data
Definition: channel_stack.h:68
grpc_call_context_element * context
Definition: channel_stack.h:69
grpc_millis deadline
Definition: channel_stack.h:72
grpc_core::CallCombiner * call_combiner
Definition: channel_stack.h:74
const grpc_slice & path
Definition: channel_stack.h:70
Definition: channel_stack.h:167
void * call_data
Definition: channel_stack.h:170
const grpc_channel_filter * filter
Definition: channel_stack.h:168
void * channel_data
Definition: channel_stack.h:169
Information about the call upon completion.
Definition: channel_stack.h:83
grpc_status_code final_status
Definition: channel_stack.h:85
grpc_call_stats stats
Definition: channel_stack.h:84
const char * error_string
Definition: channel_stack.h:86
Definition: channel_stack.h:185
size_t count
Definition: channel_stack.h:191
grpc_stream_refcount refcount
Definition: channel_stack.h:190
Definition: channel_stack.h:77
gpr_timespec latency
Definition: channel_stack.h:79
grpc_transport_stream_stats transport_stream_stats
Definition: channel_stack.h:78
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: channel_stack.h:57
const grpc_channel_args * channel_args
Definition: channel_stack.h:59
int is_first
Definition: channel_stack.h:62
int is_last
Definition: channel_stack.h:63
grpc_channel_stack * channel_stack
Definition: channel_stack.h:58
grpc_transport * optional_transport
Transport, iff it is known.
Definition: channel_stack.h:61
Definition: channel_stack.h:159
const grpc_channel_filter * filter
Definition: channel_stack.h:160
void * channel_data
Definition: channel_stack.h:161
Definition: channel_stack.h:99
size_t sizeof_channel_data
Definition: channel_stack.h:135
const char * name
Definition: channel_stack.h:154
size_t sizeof_call_data
Definition: channel_stack.h:110
Information requested from the channel.
Definition: grpc_types.h:668
Definition: channel_stack.h:175
size_t call_stack_size
Definition: channel_stack.h:180
grpc_stream_refcount refcount
Definition: channel_stack.h:176
size_t count
Definition: channel_stack.h:177
A closure over a grpc_iomgr_cb_func.
Definition: closure.h:56
Definition: error_internal.h:39
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:324
Definition: transport.h:163
Definition: transport.h:128
Definition: transport_impl.h:66