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

   1 /*
   2  *
   3  * Copyright 2016 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_BUILDER_H
  20 #define GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_BUILDER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <stdbool.h>
  25
  26 #include "src/core/lib/channel/channel_args.h"
  27 #include "src/core/lib/channel/channel_stack.h"
  28
  29 /// grpc_channel_stack_builder offers a programmatic interface to selected
  30 /// and order channel filters
  31 typedef struct grpc_channel_stack_builder grpc_channel_stack_builder;
  32 typedef struct grpc_channel_stack_builder_iterator
  33     grpc_channel_stack_builder_iterator;
  34
  35 /// Create a new channel stack builder
  36 grpc_channel_stack_builder* grpc_channel_stack_builder_create(void);
  37
  38 /// Assign a name to the channel stack: \a name must be statically allocated
  39 void grpc_channel_stack_builder_set_name(grpc_channel_stack_builder* builder,
  40                                          const char* name);
  41
  42 /// Set the target uri
  43 void grpc_channel_stack_builder_set_target(grpc_channel_stack_builder* b,
  44                                            const char* target);
  45
  46 const char* grpc_channel_stack_builder_get_target(
  47     grpc_channel_stack_builder* b);
  48
  49 /// Attach \a transport to the builder (does not take ownership)
  50 void grpc_channel_stack_builder_set_transport(
  51     grpc_channel_stack_builder* builder, grpc_transport* transport);
  52
  53 /// Fetch attached transport
  54 grpc_transport* grpc_channel_stack_builder_get_transport(
  55     grpc_channel_stack_builder* builder);
  56
  57 /// Attach \a resource_user to the builder (does not take ownership)
  58 void grpc_channel_stack_builder_set_resource_user(
  59     grpc_channel_stack_builder* builder, grpc_resource_user* resource_user);
  60
  61 /// Fetch attached resource user
  62 grpc_resource_user* grpc_channel_stack_builder_get_resource_user(
  63     grpc_channel_stack_builder* builder);
  64
  65 /// Set channel arguments: copies args
  66 void grpc_channel_stack_builder_set_channel_arguments(
  67     grpc_channel_stack_builder* builder, const grpc_channel_args* args);
  68
  69 /// Return a borrowed pointer to the channel arguments
  70 const grpc_channel_args* grpc_channel_stack_builder_get_channel_arguments(
  71     grpc_channel_stack_builder* builder);
  72
  73 /// Begin iterating over already defined filters in the builder at the beginning
  74 grpc_channel_stack_builder_iterator*
  75 grpc_channel_stack_builder_create_iterator_at_first(
  76     grpc_channel_stack_builder* builder);
  77
  78 /// Begin iterating over already defined filters in the builder at the end
  79 grpc_channel_stack_builder_iterator*
  80 grpc_channel_stack_builder_create_iterator_at_last(
  81     grpc_channel_stack_builder* builder);
  82
  83 /// Is an iterator at the first element?
  84 bool grpc_channel_stack_builder_iterator_is_first(
  85     grpc_channel_stack_builder_iterator* iterator);
  86
  87 /// Is an iterator at the end?
  88 bool grpc_channel_stack_builder_iterator_is_end(
  89     grpc_channel_stack_builder_iterator* iterator);
  90
  91 /// What is the name of the filter at this iterator position?
  92 const char* grpc_channel_stack_builder_iterator_filter_name(
  93     grpc_channel_stack_builder_iterator* iterator);
  94
  95 /// Move an iterator to the next item
  96 bool grpc_channel_stack_builder_move_next(
  97     grpc_channel_stack_builder_iterator* iterator);
  98
  99 /// Move an iterator to the previous item
 100 bool grpc_channel_stack_builder_move_prev(
 101     grpc_channel_stack_builder_iterator* iterator);
 102
 103 /// Return an iterator at \a filter_name, or at the end of the list if not
 104 /// found.
 105 grpc_channel_stack_builder_iterator* grpc_channel_stack_builder_iterator_find(
 106     grpc_channel_stack_builder* builder, const char* filter_name);
 107
 108 typedef void (*grpc_post_filter_create_init_func)(
 109     grpc_channel_stack* channel_stack, grpc_channel_element* elem, void* arg);
 110
 111 /// Add \a filter to the stack, after \a iterator.
 112 /// Call \a post_init_func(..., \a user_data) once the channel stack is
 113 /// created.
 114 bool grpc_channel_stack_builder_add_filter_after(
 115     grpc_channel_stack_builder_iterator* iterator,
 116     const grpc_channel_filter* filter,
 117     grpc_post_filter_create_init_func post_init_func,
 118     void* user_data) GRPC_MUST_USE_RESULT;
 119
 120 /// Add \a filter to the stack, before \a iterator.
 121 /// Call \a post_init_func(..., \a user_data) once the channel stack is
 122 /// created.
 123 bool grpc_channel_stack_builder_add_filter_before(
 124     grpc_channel_stack_builder_iterator* iterator,
 125     const grpc_channel_filter* filter,
 126     grpc_post_filter_create_init_func post_init_func,
 127     void* user_data) GRPC_MUST_USE_RESULT;
 128
 129 /// Add \a filter to the beginning of the filter list.
 130 /// Call \a post_init_func(..., \a user_data) once the channel stack is
 131 /// created.
 132 bool grpc_channel_stack_builder_prepend_filter(
 133     grpc_channel_stack_builder* builder, const grpc_channel_filter* filter,
 134     grpc_post_filter_create_init_func post_init_func,
 135     void* user_data) GRPC_MUST_USE_RESULT;
 136
 137 /// Add \a filter to the end of the filter list.
 138 /// Call \a post_init_func(..., \a user_data) once the channel stack is
 139 /// created.
 140 bool grpc_channel_stack_builder_append_filter(
 141     grpc_channel_stack_builder* builder, const grpc_channel_filter* filter,
 142     grpc_post_filter_create_init_func post_init_func,
 143     void* user_data) GRPC_MUST_USE_RESULT;
 144
 145 /// Remove any filter whose name is \a filter_name from \a builder. Returns true
 146 /// if \a filter_name was not found.
 147 bool grpc_channel_stack_builder_remove_filter(
 148     grpc_channel_stack_builder* builder, const char* filter_name);
 149
 150 /// Terminate iteration and destroy \a iterator
 151 void grpc_channel_stack_builder_iterator_destroy(
 152     grpc_channel_stack_builder_iterator* iterator);
 153
 154 /// Destroy the builder, return the freshly minted channel stack in \a result.
 155 /// Allocates \a prefix_bytes bytes before the channel stack
 156 /// Returns the base pointer of the allocated block
 157 /// \a initial_refs, \a destroy, \a destroy_arg are as per
 158 /// grpc_channel_stack_init
 159 grpc_error* grpc_channel_stack_builder_finish(
 160     grpc_channel_stack_builder* builder, size_t prefix_bytes, int initial_refs,
 161     grpc_iomgr_cb_func destroy, void* destroy_arg, void** result);
 162
 163 /// Destroy the builder without creating a channel stack
 164 void grpc_channel_stack_builder_destroy(grpc_channel_stack_builder* builder);
 165
 166 #endif /* GRPC_CORE_LIB_CHANNEL_CHANNEL_STACK_BUILDER_H */