GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
channel_stack.h
Go to the documentation of this file.
1 /*
2 *
3 * Copyright 2015, Google Inc.
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above
13 * copyright notice, this list of conditions and the following disclaimer
14 * in the documentation and/or other materials provided with the
15 * distribution.
16 * * Neither the name of Google Inc. nor the names of its
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33
34 #ifndef GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_STACK_H
35 #define GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_STACK_H
36
37 /* A channel filter defines how operations on a channel are implemented.
38 Channel filters are chained together to create full channels, and if those
39 chains are linear, then channel stacks provide a mechanism to minimize
40 allocations for that chain.
41 Call stacks are created by channel stacks and represent the per-call data
42 for that stack. */
43
44 #include <stddef.h>
45
46 #include <grpc/grpc.h>
47 #include <grpc/support/log.h>
48 #include "src/core/debug/trace.h"
49 #include "src/core/transport/transport.h"
50
51 typedef struct grpc_channel_element grpc_channel_element;
52 typedef struct grpc_call_element grpc_call_element;
53
54 /* Channel filters specify:
55 1. the amount of memory needed in the channel & call (via the sizeof_XXX
56 members)
57 2. functions to initialize and destroy channel & call data
58 (init_XXX, destroy_XXX)
59 3. functions to implement call operations and channel operations (call_op,
60 channel_op)
61 4. a name, which is useful when debugging
62
63 Members are laid out in approximate frequency of use order. */
64 typedef struct {
65 /* Called to eg. send/receive data on a call.
66 See grpc_call_next_op on how to call the next element in the stack */
67 void (*start_transport_stream_op)(grpc_call_element *elem,
68 grpc_transport_stream_op *op);
69 /* Called to handle channel level operations - e.g. new calls, or transport
70 closure.
71 See grpc_channel_next_op on how to call the next element in the stack */
72 void (*start_transport_op)(grpc_channel_element *elem, grpc_transport_op *op);
73
74 /* sizeof(per call data) */
75 size_t sizeof_call_data;
76 /* Initialize per call data.
77 elem is initialized at the start of the call, and elem->call_data is what
78 needs initializing.
79 The filter does not need to do any chaining.
80 server_transport_data is an opaque pointer. If it is NULL, this call is
81 on a client; if it is non-NULL, then it points to memory owned by the
82 transport and is on the server. Most filters want to ignore this
83 argument.*/
84 void (*init_call_elem)(grpc_call_element *elem,
85 const void *server_transport_data,
86 grpc_transport_stream_op *initial_op);
87 /* Destroy per call data.
88 The filter does not need to do any chaining */
89 void (*destroy_call_elem)(grpc_call_element *elem);
90
91 /* sizeof(per channel data) */
92 size_t sizeof_channel_data;
93 /* Initialize per-channel data.
94 elem is initialized at the start of the call, and elem->channel_data is
95 what needs initializing.
96 is_first, is_last designate this elements position in the stack, and are
97 useful for asserting correct configuration by upper layer code.
98 The filter does not need to do any chaining */
99 void (*init_channel_elem)(grpc_channel_element *elem, grpc_channel *master,
100 const grpc_channel_args *args,
101 grpc_mdctx *metadata_context, int is_first,
102 int is_last);
103 /* Destroy per channel data.
104 The filter does not need to do any chaining */
105 void (*destroy_channel_elem)(grpc_channel_element *elem);
106
107 /* Implement grpc_call_get_peer() */
108 char *(*get_peer)(grpc_call_element *elem);
109
110 /* The name of this filter */
111 const char *name;
112 } grpc_channel_filter;
113
114 /* A channel_element tracks its filter and the filter requested memory within
115 a channel allocation */
116 struct grpc_channel_element {
117 const grpc_channel_filter *filter;
118 void *channel_data;
119 };
120
121 /* A call_element tracks its filter, the filter requested memory within
122 a channel allocation, and the filter requested memory within a call
123 allocation */
124 struct grpc_call_element {
125 const grpc_channel_filter *filter;
126 void *channel_data;
127 void *call_data;
128 };
129
130 /* A channel stack tracks a set of related filters for one channel, and
131 guarantees they live within a single malloc() allocation */
132 typedef struct {
133 size_t count;
134 /* Memory required for a call stack (computed at channel stack
135 initialization) */
136 size_t call_stack_size;
137 } grpc_channel_stack;
138
139 /* A call stack tracks a set of related filters for one call, and guarantees
140 they live within a single malloc() allocation */
141 typedef struct { size_t count; } grpc_call_stack;
142
143 /* Get a channel element given a channel stack and its index */
144 grpc_channel_element *grpc_channel_stack_element(grpc_channel_stack *stack,
145 size_t i);
146 /* Get the last channel element in a channel stack */
147 grpc_channel_element *grpc_channel_stack_last_element(
148 grpc_channel_stack *stack);
149 /* Get a call stack element given a call stack and an index */
150 grpc_call_element *grpc_call_stack_element(grpc_call_stack *stack, size_t i);
151
152 /* Determine memory required for a channel stack containing a set of filters */
153 size_t grpc_channel_stack_size(const grpc_channel_filter **filters,
154 size_t filter_count);
155 /* Initialize a channel stack given some filters */
156 void grpc_channel_stack_init(const grpc_channel_filter **filters,
157 size_t filter_count, grpc_channel *master,
158 const grpc_channel_args *args,
159 grpc_mdctx *metadata_context,
160 grpc_channel_stack *stack);
161 /* Destroy a channel stack */
162 void grpc_channel_stack_destroy(grpc_channel_stack *stack);
163
164 /* Initialize a call stack given a channel stack. transport_server_data is
165 expected to be NULL on a client, or an opaque transport owned pointer on the
166 server. */
167 void grpc_call_stack_init(grpc_channel_stack *channel_stack,
168 const void *transport_server_data,
169 grpc_transport_stream_op *initial_op,
170 grpc_call_stack *call_stack);
171 /* Destroy a call stack */
172 void grpc_call_stack_destroy(grpc_call_stack *stack);
173
174 /* Call the next operation in a call stack */
175 void grpc_call_next_op(grpc_call_element *elem, grpc_transport_stream_op *op);
176 /* Call the next operation (depending on call directionality) in a channel
177 stack */
178 void grpc_channel_next_op(grpc_channel_element *elem, grpc_transport_op *op);
179 /* Pass through a request to get_peer to the next child element */
180 char *grpc_call_next_get_peer(grpc_call_element *elem);
181
182 /* Given the top element of a channel stack, get the channel stack itself */
183 grpc_channel_stack *grpc_channel_stack_from_top_element(
184 grpc_channel_element *elem);
185 /* Given the top element of a call stack, get the call stack itself */
186 grpc_call_stack *grpc_call_stack_from_top_element(grpc_call_element *elem);
187
188 void grpc_call_log_op(char *file, int line, gpr_log_severity severity,
189 grpc_call_element *elem, grpc_transport_stream_op *op);
190
191 void grpc_call_element_send_cancel(grpc_call_element *cur_elem);
192
193 extern int grpc_trace_channel;
194
195 #define GRPC_CALL_LOG_OP(sev, elem, op) \
196 if (grpc_trace_channel) grpc_call_log_op(sev, elem, op)
197
198 #endif /* GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_STACK_H */
grpc_channel_filter
Definition: channel_stack.h:64
grpc_call_stack::count
size_t count
Definition: channel_stack.h:141
grpc_channel_stack
Definition: channel_stack.h:132
trace.h
grpc_call_stack_init
void grpc_call_stack_init(grpc_channel_stack *channel_stack, const void *transport_server_data, grpc_transport_stream_op *initial_op, grpc_call_stack *call_stack)
Definition: channel_stack.c:151
grpc_call_next_get_peer
char * grpc_call_next_get_peer(grpc_call_element *elem)
Definition: channel_stack.c:194
grpc_trace_channel
int grpc_trace_channel
Definition: channel_stack.c:40
transport.h
grpc_channel_args
An array of arguments that can be passed around.
Definition: grpc.h:113
grpc_channel
Definition: channel.c:61
grpc_channel_filter::sizeof_channel_data
size_t sizeof_channel_data
Definition: channel_stack.h:92
grpc_transport_stream_op
Definition: transport.h:66
grpc_call_next_op
void grpc_call_next_op(grpc_call_element *elem, grpc_transport_stream_op *op)
Definition: channel_stack.c:189
grpc_channel_stack::count
size_t count
Definition: channel_stack.h:133
grpc_channel_stack_init
void grpc_channel_stack_init(const grpc_channel_filter **filters, size_t filter_count, grpc_channel *master, const grpc_channel_args *args, grpc_mdctx *metadata_context, grpc_channel_stack *stack)
Definition: channel_stack.c:104
grpc_channel_stack_from_top_element
grpc_channel_stack * grpc_channel_stack_from_top_element(grpc_channel_element *elem)
Definition: channel_stack.c:204
grpc_channel_filter::sizeof_call_data
size_t sizeof_call_data
Definition: channel_stack.h:75
grpc_call_element_send_cancel
void grpc_call_element_send_cancel(grpc_call_element *cur_elem)
Definition: channel_stack.c:215
grpc_channel_element::channel_data
void * channel_data
Definition: channel_stack.h:118
grpc_channel_element::filter
const grpc_channel_filter * filter
Definition: channel_stack.h:117
gpr_log_severity
gpr_log_severity
Definition: log.h:56
grpc_channel_stack_destroy
void grpc_channel_stack_destroy(grpc_channel_stack *stack)
Definition: channel_stack.c:140
grpc_call_stack_from_top_element
grpc_call_stack * grpc_call_stack_from_top_element(grpc_call_element *elem)
Definition: channel_stack.c:210
grpc_mdctx
Definition: metadata.c:98
grpc_call_element::filter
const grpc_channel_filter * filter
Definition: channel_stack.h:125
grpc_channel_stack_size
size_t grpc_channel_stack_size(const grpc_channel_filter **filters, size_t filter_count)
Definition: channel_stack.c:62
grpc_call_stack_destroy
void grpc_call_stack_destroy(grpc_call_stack *stack)
Definition: channel_stack.c:178
grpc_channel_next_op
void grpc_channel_next_op(grpc_channel_element *elem, grpc_transport_op *op)
Definition: channel_stack.c:199
grpc_call_log_op
void grpc_call_log_op(char *file, int line, gpr_log_severity severity, grpc_call_element *elem, grpc_transport_stream_op *op)
Definition: transport_op_string.c:161
grpc_call_element::call_data
void * call_data
Definition: channel_stack.h:127
grpc_call_stack
Definition: channel_stack.h:141
grpc_channel_element
Definition: channel_stack.h:116
grpc_channel_stack_last_element
grpc_channel_element * grpc_channel_stack_last_element(grpc_channel_stack *stack)
Definition: channel_stack.c:94
grpc_call_element
Definition: channel_stack.h:124
grpc_call_stack_element
grpc_call_element * grpc_call_stack_element(grpc_call_stack *stack, size_t i)
Definition: channel_stack.c:99
grpc_channel_stack::call_stack_size
size_t call_stack_size
Definition: channel_stack.h:136
log.h
grpc.h
grpc_channel_filter::name
const char * name
Definition: channel_stack.h:111
grpc_call_element::channel_data
void * channel_data
Definition: channel_stack.h:126
grpc_channel_stack_element
grpc_channel_element * grpc_channel_stack_element(grpc_channel_stack *stack, size_t i)
Definition: channel_stack.c:89
grpc_transport_op
Transport op: a set of operations to perform on a transport as a whole.
Definition: transport.h:90