legacy-libs/grpc/deps/grpc/src/core/lib/channel/channel_stack.h

   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/time_precise.h"
  46 #include "src/core/lib/gprpp/arena.h"
  47 #include "src/core/lib/iomgr/call_combiner.h"
  48 #include "src/core/lib/iomgr/polling_entity.h"
  49 #include "src/core/lib/transport/transport.h"
  50
  51 typedef struct grpc_channel_element grpc_channel_element;
  52 typedef struct grpc_call_element grpc_call_element;
  53
  54 typedef struct grpc_channel_stack grpc_channel_stack;
  55 typedef struct grpc_call_stack grpc_call_stack;
  56
  57 typedef struct {
  58   grpc_channel_stack* channel_stack;
  59   const grpc_channel_args* channel_args;
  60   /** Transport, iff it is known */
  61   grpc_transport* optional_transport;
  62   int is_first;
  63   int is_last;
  64 } grpc_channel_element_args;
  65
  66 typedef struct {
  67   grpc_call_stack* call_stack;
  68   const void* server_transport_data;
  69   grpc_call_context_element* context;
  70   const grpc_slice& path;
  71   gpr_cycle_counter start_time;
  72   grpc_millis deadline;
  73   grpc_core::Arena* arena;
  74   grpc_core::CallCombiner* call_combiner;
  75 } grpc_call_element_args;
  76
  77 typedef struct {
  78   grpc_transport_stream_stats transport_stream_stats;
  79   gpr_timespec latency; /* From call creating to enqueing of received status */
  80 } grpc_call_stats;
  81
  82 /** Information about the call upon completion. */
  83 struct grpc_call_final_info {
  84   grpc_call_stats stats;
  85   grpc_status_code final_status = GRPC_STATUS_OK;
  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,
 103                                           grpc_transport_stream_op_batch* op);
 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) */
 110   size_t sizeof_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) */
 135   size_t sizeof_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,
 144                                    grpc_channel_element_args* args);
 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;
 155 } grpc_channel_filter;
 156
 157 /* A channel_element tracks its filter and the filter requested memory within
 158    a channel allocation */
 159 struct grpc_channel_element {
 160   const grpc_channel_filter* filter;
 161   void* channel_data;
 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 */
 167 struct grpc_call_element {
 168   const grpc_channel_filter* filter;
 169   void* channel_data;
 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 */
 175 struct grpc_channel_stack {
 176   grpc_stream_refcount refcount;
 177   size_t count;
 178   /* Memory required for a call stack (computed at channel stack
 179      initialization) */
 180   size_t call_stack_size;
 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 */
 185 struct grpc_call_stack {
 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. */
 190   grpc_stream_refcount refcount;
 191   size_t count;
 192 };
 193
 194 /* Get a channel element given a channel stack and its index */
 195 grpc_channel_element* grpc_channel_stack_element(grpc_channel_stack* stack,
 196                                                  size_t i);
 197 /* Get the last channel element in a channel stack */
 198 grpc_channel_element* grpc_channel_stack_last_element(
 199     grpc_channel_stack* stack);
 200 /* Get a call stack element given a call stack and an index */
 201 grpc_call_element* grpc_call_stack_element(grpc_call_stack* stack, size_t i);
 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 */
 207 grpc_error* grpc_channel_stack_init(
 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 */
 213 void grpc_channel_stack_destroy(grpc_channel_stack* 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. */
 218 grpc_error* grpc_call_stack_init(grpc_channel_stack* channel_stack,
 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 */
 224 void grpc_call_stack_set_pollset_or_pollset_set(grpc_call_stack* call_stack,
 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   grpc_stream_ref(&(call_stack)->refcount)
 239 #define GRPC_CALL_STACK_UNREF(call_stack, reason) \
 240   grpc_stream_unref(&(call_stack)->refcount)
 241 #define GRPC_CHANNEL_STACK_REF(channel_stack, reason) \
 242   grpc_stream_ref(&(channel_stack)->refcount)
 243 #define GRPC_CHANNEL_STACK_UNREF(channel_stack, reason) \
 244   grpc_stream_unref(&(channel_stack)->refcount)
 245 #endif
 246
 247 /* Destroy a call stack */
 248 void grpc_call_stack_destroy(grpc_call_stack* stack,
 249                              const grpc_call_final_info* final_info,
 250                              grpc_closure* then_schedule_closure);
 251
 252 /* Ignore set pollset{_set} - used by filters if they don't care about pollsets
 253  * at all. Does nothing. */
 254 void grpc_call_stack_ignore_set_pollset_or_pollset_set(
 255     grpc_call_element* elem, grpc_polling_entity* pollent);
 256 /* Call the next operation in a call stack */
 257 void grpc_call_next_op(grpc_call_element* elem,
 258                        grpc_transport_stream_op_batch* op);
 259 /* Call the next operation (depending on call directionality) in a channel
 260    stack */
 261 void grpc_channel_next_op(grpc_channel_element* elem, grpc_transport_op* op);
 262 /* Pass through a request to get_channel_info() to the next child element */
 263 void grpc_channel_next_get_info(grpc_channel_element* elem,
 264                                 const grpc_channel_info* channel_info);
 265
 266 /* Given the top element of a channel stack, get the channel stack itself */
 267 grpc_channel_stack* grpc_channel_stack_from_top_element(
 268     grpc_channel_element* elem);
 269 /* Given the top element of a call stack, get the call stack itself */
 270 grpc_call_stack* grpc_call_stack_from_top_element(grpc_call_element* elem);
 271
 272 void grpc_call_log_op(const char* file, int line, gpr_log_severity severity,
 273                       grpc_call_element* elem,
 274                       grpc_transport_stream_op_batch* op);
 275
 276 extern grpc_core::TraceFlag grpc_trace_channel;
 277
 278 #define GRPC_CALL_LOG_OP(sev, elem, op)                \
 279   do {                                                 \
 280     if (GRPC_TRACE_FLAG_ENABLED(grpc_trace_channel)) { \
 281       grpc_call_log_op(sev, elem, op);                 \
 282     }                                                  \
 283   } while (0)
 284
 285 #endif /* GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_H */