Google Cloud C++ Client  1.32.1
C++ Client Library for Google Cloud Platform
grpc_options.h
Go to the documentation of this file.
1 // Copyright 2021 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_GRPC_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_GRPC_OPTIONS_H
17 
18 #include "google/cloud/background_threads.h"
19 #include "google/cloud/completion_queue.h"
20 #include "google/cloud/options.h"
21 #include "google/cloud/tracing_options.h"
22 #include "google/cloud/version.h"
23 #include <grpcpp/grpcpp.h>
24 #include <map>
25 #include <string>
26 
27 namespace google {
28 namespace cloud {
29 inline namespace GOOGLE_CLOUD_CPP_NS {
30 
31 /**
32  * The gRPC credentials used by clients configured with this object.
33  */
35  using Type = std::shared_ptr<grpc::ChannelCredentials>;
36 };
37 
38 /**
39  * The number of transport channels to create.
40  *
41  * gRPC limits the number of simultaneous calls in progress on a channel to
42  * 100. Increasing the number of channels thus increases the number of
43  * operations that can be in progress in parallel.
44  */
46  using Type = int;
47 };
48 
49 /**
50  * A string-string map of arguments for `grpc::ChannelArguments::SetString`.
51  *
52  * This option gives users the ability to set various arguments for the
53  * underlying `grpc::ChannelArguments` objects that will be created. See the
54  * gRPC documentation for more details about available channel arguments.
55  *
56  * @note Our library will always start with the native object from
57  * `GrpcChannelArgumentsNativeOption`, then add the channel arguments from this
58  * option. Users are cautioned not to set the same channel argument to different
59  * values in different options as gRPC will use the first value set for some
60  * channel arguments, and the last value set for others.
61  *
62  * @see https://grpc.github.io/grpc/cpp/classgrpc_1_1_channel_arguments.html
63  * @see https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
64  */
66  using Type = std::map<std::string, std::string>;
67 };
68 
69 /**
70  * The native `grpc::ChannelArguments` object.
71  *
72  * This option gives users full control over the `grpc::ChannelArguments`
73  * objects that will be created. See the gRPC documentation for more details
74  * about available channel arguments.
75  *
76  * @note Our library will always start with the native object, then add in the
77  * channel arguments from `GrpcChannelArgumentsOption`, then add the user agent
78  * prefix from `UserAgentProductsOption`. Users are cautioned not to set the
79  * same channel argument to different values in different options as gRPC will
80  * use the first value set for some channel arguments, and the last value set
81  * for others.
82  *
83  * @see https://grpc.github.io/grpc/cpp/classgrpc_1_1_channel_arguments.html
84  * @see https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
85  */
87  using Type = grpc::ChannelArguments;
88 };
89 
90 /**
91  * The `TracingOptions` to use when printing grpc protocol buffer messages.
92  */
94  using Type = TracingOptions;
95 };
96 
97 /**
98  * The size of the background thread pool
99  *
100  * These threads are created by the client library to run a `CompletionQueue`
101  * which performs background work for gRPC.
102  *
103  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
104  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive. This option
105  * will be ignored if either `GrpcCompletionQueueOption` or
106  * `GrpcBackgroundThreadsFactoryOption` are set.
107  */
109  using Type = std::size_t;
110 };
111 
112 /**
113  * The `CompletionQueue` to use for background gRPC work.
114  *
115  * If this option is set, the library will use the supplied `CompletionQueue`
116  * instead of its own. The caller is responsible for making sure there are
117  * thread(s) servicing this `CompletionQueue`. The client library will not
118  * create any background threads or attempt to call `CompletionQueue::Run()`.
119  *
120  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
121  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive.
122  */
124  using Type = CompletionQueue;
125 };
126 
127 using BackgroundThreadsFactory =
128  std::function<std::unique_ptr<BackgroundThreads>()>;
129 /**
130  * Changes the `BackgroundThreadsFactory`.
131  *
132  * Connections need to perform background work on behalf of the application.
133  * Normally they just create a background thread and a `CompletionQueue` for
134  * this work, but the application may need more fine-grained control of their
135  * threads.
136  *
137  * In this case the application can provide its own `BackgroundThreadsFactory`
138  * and it assumes responsibility for creating one or more threads blocked on its
139  * `CompletionQueue::Run()`.
140  *
141  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
142  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive. This option
143  * will be ignored if `GrpcCompletionQueueOption` is set.
144  */
146  using Type = BackgroundThreadsFactory;
147 };
148 
149 /**
150  * A list of all the gRPC options.
151  */
152 using GrpcOptionList =
157 
158 namespace internal {
159 
160 /// Creates a new `grpc::ChannelArguments` configured with @p opts.
161 grpc::ChannelArguments MakeChannelArguments(Options const& opts);
162 
163 /// Helper function to extract the first instance of an integer channel argument
164 absl::optional<int> GetIntChannelArgument(grpc::ChannelArguments const& args,
165  std::string const& key);
166 
167 /// Helper function to extract the first instance of a string channel argument
168 absl::optional<std::string> GetStringChannelArgument(
169  grpc::ChannelArguments const& args, std::string const& key);
170 
171 /**
172  * Returns a factory for generating `BackgroundThreads`.
173  *
174  * If `GrpcBackgroundThreadsFactoryOption` is unset, it will return a thread
175  * pool of size `GrpcBackgroundThreadPoolSizeOption`.
176  */
177 BackgroundThreadsFactory MakeBackgroundThreadsFactory(Options const& opts = {});
178 
179 } // namespace internal
180 } // namespace GOOGLE_CLOUD_CPP_NS
181 } // namespace cloud
182 } // namespace google
183 
184 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_GRPC_OPTIONS_H