Google Cloud C++ Client  2.4.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  *
45  * @note This option only applies when passed to the following functions:
46  * - `bigtable::MakeDataConnection()`
47  * - `pubsub::MakePublisherConnection()`
48  * - `pubsub::MakeSubscriberConnection()`
49  * - `spanner::MakeConnection()`
50  * - `storage_experimental::DefaultGrpcClient()`
51  */
53  using Type = int;
54 };
55 
56 /**
57  * A string-string map of arguments for `grpc::ChannelArguments::SetString`.
58  *
59  * This option gives users the ability to set various arguments for the
60  * underlying `grpc::ChannelArguments` objects that will be created. See the
61  * gRPC documentation for more details about available channel arguments.
62  *
63  * @note Our library will always start with the native object from
64  * `GrpcChannelArgumentsNativeOption`, then add the channel arguments from this
65  * option. Users are cautioned not to set the same channel argument to different
66  * values in different options as gRPC will use the first value set for some
67  * channel arguments, and the last value set for others.
68  *
69  * @see https://grpc.github.io/grpc/cpp/classgrpc_1_1_channel_arguments.html
70  * @see https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
71  */
73  using Type = std::map<std::string, std::string>;
74 };
75 
76 /**
77  * The native `grpc::ChannelArguments` object.
78  *
79  * This option gives users full control over the `grpc::ChannelArguments`
80  * objects that will be created. See the gRPC documentation for more details
81  * about available channel arguments.
82  *
83  * @note Our library will always start with the native object, then add in the
84  * channel arguments from `GrpcChannelArgumentsOption`, then add the user agent
85  * prefix from `UserAgentProductsOption`. Users are cautioned not to set the
86  * same channel argument to different values in different options as gRPC will
87  * use the first value set for some channel arguments, and the last value set
88  * for others.
89  *
90  * @see https://grpc.github.io/grpc/cpp/classgrpc_1_1_channel_arguments.html
91  * @see https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
92  */
94  using Type = grpc::ChannelArguments;
95 };
96 
97 /**
98  * The `TracingOptions` to use when printing grpc protocol buffer messages.
99  */
101  using Type = TracingOptions;
102 };
103 
104 /**
105  * The size of the background thread pool
106  *
107  * These threads are created by the client library to run a `CompletionQueue`
108  * which performs background work for gRPC.
109  *
110  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
111  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive. This option
112  * will be ignored if either `GrpcCompletionQueueOption` or
113  * `GrpcBackgroundThreadsFactoryOption` are set.
114  */
116  using Type = std::size_t;
117 };
118 
119 /**
120  * The `CompletionQueue` to use for background gRPC work.
121  *
122  * If this option is set, the library will use the supplied `CompletionQueue`
123  * instead of its own. The caller is responsible for making sure there are
124  * thread(s) servicing this `CompletionQueue`. The client library will not
125  * create any background threads or attempt to call `CompletionQueue::Run()`.
126  *
127  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
128  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive.
129  */
131  using Type = CompletionQueue;
132 };
133 
134 using BackgroundThreadsFactory =
135  std::function<std::unique_ptr<BackgroundThreads>()>;
136 
137 /**
138  * Changes the `BackgroundThreadsFactory`.
139  *
140  * Connections need to perform background work on behalf of the application.
141  * Normally they just create a background thread and a `CompletionQueue` for
142  * this work, but the application may need more fine-grained control of their
143  * threads.
144  *
145  * In this case the application can provide its own `BackgroundThreadsFactory`
146  * and it assumes responsibility for creating one or more threads blocked on its
147  * `CompletionQueue::Run()`.
148  *
149  * @note `GrpcBackgroundThreadPoolSizeOption`, `GrpcCompletionQueueOption`, and
150  * `GrpcBackgroundThreadsFactoryOption` are mutually exclusive. This option
151  * will be ignored if `GrpcCompletionQueueOption` is set.
152  */
154  using Type = BackgroundThreadsFactory;
155 };
156 
157 /**
158  * A list of all the gRPC options.
159  */
160 using GrpcOptionList =
165 
166 namespace internal {
167 
168 /**
169  * A generic function to directly configure a gRPC context.
170  *
171  * This function takes effect before the context is used to make any requests.
172  *
173  * @warning It is NOT recommended to call `set_auth_context()` or
174  * `set_credentials()` directly on the context. Instead, use the Google
175  * Unified Auth Credentials library, via
176  * #google::cloud::UnifiedCredentialsOption.
177  */
178 struct GrpcSetupOption {
179  using Type = std::function<void(grpc::ClientContext&)>;
180 };
181 
182 /**
183  * A generic function to directly configure a gRPC context for polling
184  * long-running operations.
185  *
186  * This function takes effect before the context is used to make any poll or
187  * cancel requests for long-running operations.
188  *
189  * @warning It is NOT recommended to call `set_auth_context()` or
190  * `set_credentials()` directly on the context. Instead, use the Google
191  * Unified Auth Credentials library, via
192  * #google::cloud::UnifiedCredentialsOption.
193  */
194 struct GrpcSetupPollOption {
195  using Type = std::function<void(grpc::ClientContext&)>;
196 };
197 
198 /// Configure the ClientContext using options.
199 void ConfigureContext(grpc::ClientContext& context, Options const& opts);
200 
201 /// Configure the ClientContext for polling operations using options.
202 void ConfigurePollContext(grpc::ClientContext& context, Options const& opts);
203 
204 /// Creates a new `grpc::ChannelArguments` configured with @p opts.
205 grpc::ChannelArguments MakeChannelArguments(Options const& opts);
206 
207 /// Helper function to extract the first instance of an integer channel argument
208 absl::optional<int> GetIntChannelArgument(grpc::ChannelArguments const& args,
209  std::string const& key);
210 
211 /// Helper function to extract the first instance of a string channel argument
212 absl::optional<std::string> GetStringChannelArgument(
213  grpc::ChannelArguments const& args, std::string const& key);
214 
215 /**
216  * Returns a factory for generating `BackgroundThreads`.
217  *
218  * If `GrpcBackgroundThreadsFactoryOption` is unset, it will return a thread
219  * pool of size `GrpcBackgroundThreadPoolSizeOption`.
220  */
221 BackgroundThreadsFactory MakeBackgroundThreadsFactory(Options const& opts = {});
222 
223 } // namespace internal
225 } // namespace cloud
226 } // namespace google
227 
228 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_GRPC_OPTIONS_H