Google Cloud C++ Client  2.1.0
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 // https://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 {
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 /**
131  * Changes the `BackgroundThreadsFactory`.
132  *
133  * Connections need to perform background work on behalf of the application.
134  * Normally they just create a background thread and a `CompletionQueue` for
135  * this work, but the application may need more fine-grained control of their
136  * threads.
137  *
138  * In this case the application can provide its own `BackgroundThreadsFactory`
139  * and it assumes responsibility for creating one or more threads blocked on its
140  * `CompletionQueue::Run()`.
141  *
142  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
143  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive. This option
144  * will be ignored if `GrpcCompletionQueueOption` is set.
145  */
147  using Type = BackgroundThreadsFactory;
148 };
149 
150 /**
151  * A list of all the gRPC options.
152  */
153 using GrpcOptionList =
158 
159 namespace internal {
160 
161 /**
162  * A generic function to directly configure a gRPC context.
163  *
164  * This function takes effect before the context is used to make any requests.
165  *
166  * @warning It is NOT recommended to call `set_auth_context()` or
167  * `set_credentials()` directly on the context. Instead, use the Google
168  * Unified Auth Credentials library, via
169  * #google::cloud::UnifiedCredentialsOption.
170  */
171 struct GrpcSetupOption {
172  using Type = std::function<void(grpc::ClientContext&)>;
173 };
174 
175 /**
176  * A generic function to directly configure a gRPC context for polling
177  * long-running operations.
178  *
179  * This function takes effect before the context is used to make any poll or
180  * cancel requests for long-running operations.
181  *
182  * @warning It is NOT recommended to call `set_auth_context()` or
183  * `set_credentials()` directly on the context. Instead, use the Google
184  * Unified Auth Credentials library, via
185  * #google::cloud::UnifiedCredentialsOption.
186  */
187 struct GrpcSetupPollOption {
188  using Type = std::function<void(grpc::ClientContext&)>;
189 };
190 
191 /// Configure the ClientContext using options.
192 void ConfigureContext(grpc::ClientContext& context, Options const& opts);
193 
194 /// Configure the ClientContext for polling operations using options.
195 void ConfigurePollContext(grpc::ClientContext& context, Options const& opts);
196 
197 /// Creates a new `grpc::ChannelArguments` configured with @p opts.
198 grpc::ChannelArguments MakeChannelArguments(Options const& opts);
199 
200 /// Helper function to extract the first instance of an integer channel argument
201 absl::optional<int> GetIntChannelArgument(grpc::ChannelArguments const& args,
202  std::string const& key);
203 
204 /// Helper function to extract the first instance of a string channel argument
205 absl::optional<std::string> GetStringChannelArgument(
206  grpc::ChannelArguments const& args, std::string const& key);
207 
208 /**
209  * Returns a factory for generating `BackgroundThreads`.
210  *
211  * If `GrpcBackgroundThreadsFactoryOption` is unset, it will return a thread
212  * pool of size `GrpcBackgroundThreadPoolSizeOption`.
213  */
214 BackgroundThreadsFactory MakeBackgroundThreadsFactory(Options const& opts = {});
215 
216 } // namespace internal
218 } // namespace cloud
219 } // namespace google
220 
221 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_GRPC_OPTIONS_H