Google Cloud C++ Client  2.1.0
C++ Client Library for Google Cloud Platform
connection_options.h
Go to the documentation of this file.
1 // Copyright 2020 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_CONNECTION_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_CONNECTION_OPTIONS_H
17 
18 #include "google/cloud/common_options.h"
19 #include "google/cloud/completion_queue.h"
20 #include "google/cloud/grpc_options.h"
21 #include "google/cloud/internal/algorithm.h"
22 #include "google/cloud/internal/background_threads_impl.h"
23 #include "google/cloud/internal/populate_common_options.h"
24 #include "google/cloud/internal/populate_grpc_options.h"
25 #include "google/cloud/options.h"
26 #include "google/cloud/status_or.h"
27 #include "google/cloud/tracing_options.h"
28 #include "google/cloud/version.h"
29 #include <grpcpp/grpcpp.h>
30 #include <functional>
31 #include <memory>
32 #include <set>
33 #include <string>
34 
35 namespace google {
36 namespace cloud {
38 
39 template <typename ConnectionTraits>
40 class ConnectionOptions;
41 
42 namespace internal {
43 std::unique_ptr<BackgroundThreads> DefaultBackgroundThreads(std::size_t);
44 template <typename ConnectionTraits>
45 Options MakeOptions(ConnectionOptions<ConnectionTraits>);
46 } // namespace internal
47 
48 /**
49  * The configuration parameters for client connections.
50  *
51  * @deprecated Use `Options` instead.
52  */
53 template <typename ConnectionTraits>
54 class ConnectionOptions {
55  public:
56  /**
57  * The default options, using `grpc::GoogleDefaultCredentials()`.
58  *
59  * @deprecated Use `Options` instead.
60  */
61  ConnectionOptions() : ConnectionOptions(grpc::GoogleDefaultCredentials()) {}
62 
63  /**
64  * The default options, using an explicit credentials object.
65  *
66  * @deprecated Use `Options` instead.
67  */
69  std::shared_ptr<grpc::ChannelCredentials> credentials)
70  : opts_(Options{}
71  .set<GrpcCredentialOption>(std::move(credentials))
73  internal::DefaultTracingComponents())
75  internal::DefaultTracingOptions())
76  .template set<EndpointOption>(
77  ConnectionTraits::default_endpoint())
78  .template set<GrpcNumChannelsOption>(
79  ConnectionTraits::default_num_channels())),
80  user_agent_prefix_(ConnectionTraits::user_agent_prefix()) {}
81 
82  /**
83  * Change the gRPC credentials value.
84  *
85  * @deprecated Use `Options` and `UnifiedCredentialsOption`.
86  */
87  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `UnifiedCredentialsOption`")
88  ConnectionOptions& set_credentials(
89  std::shared_ptr<grpc::ChannelCredentials> v) {
90  opts_.set<GrpcCredentialOption>(std::move(v));
91  return *this;
92  }
93 
94  /**
95  * The gRPC credentials used by clients configured with this object.
96  *
97  * @deprecated Use `Options` and `UnifiedCredentialsOption`.
98  */
99  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `UnifiedCredentialsOption`")
100  std::shared_ptr<grpc::ChannelCredentials> credentials() const {
101  return opts_.get<GrpcCredentialOption>();
102  }
103 
104  /**
105  * Change the gRPC endpoint.
106  *
107  * In almost all cases the default is the correct endpoint to use.
108  * Applications may need to be changed to (1) test against a fake or
109  * simulator, or (2) to use a beta or EAP version of the service.
110  *
111  * The default value is set by `ConnectionTraits::default_endpoint()`.
112  *
113  * @deprecated Use `Options` and `EndpointOption`.
114  */
115  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `EndpointOption`")
116  ConnectionOptions& set_endpoint(std::string v) {
117  opts_.set<EndpointOption>(std::move(v));
118  return *this;
119  }
120 
121  /**
122  * The endpoint used by clients configured with this object.
123  *
124  * @deprecated Use `Options` and `EndpointOption`.
125  */
126  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `EndpointOption`")
127  std::string const& endpoint() const { return opts_.get<EndpointOption>(); }
128 
129  /**
130  * The number of transport channels to create.
131  *
132  * Some transports limit the number of simultaneous calls in progress on a
133  * channel (for gRPC the limit is 100). Increasing the number of channels
134  * thus increases the number of operations that can be in progress in
135  * parallel.
136  *
137  * The default value is set by `ConnectionTraits::default_num_channels()`.
138  *
139  * @deprecated Use `Options` and `GrpcNumChannelsOption`
140  */
141  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcNumChannelsOption`")
142  int num_channels() const { return opts_.get<GrpcNumChannelsOption>(); }
143 
144  /**
145  * Set the value for `num_channels()`.
146  *
147  * @deprecated Use `Options` and `GrpcNumChannelsOption`
148  */
149  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcNumChannelsOption`")
150  ConnectionOptions& set_num_channels(int num_channels) {
151  opts_.set<GrpcNumChannelsOption>(num_channels);
152  return *this;
153  }
154 
155  /**
156  * Return whether tracing is enabled for the given @p component.
157  *
158  * The C++ clients can log interesting events to help library and application
159  * developers troubleshoot problems. This flag returns true if tracing should
160  * be enabled by clients configured with this option.
161  *
162  * @deprecated Use `Options` and `TracingComponentsOption`
163  */
164  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `TracingComponentsOption`")
165  bool tracing_enabled(std::string const& component) const {
166  return internal::Contains(opts_.get<TracingComponentsOption>(), component);
167  }
168 
169  /**
170  * Enable tracing for @p component in clients configured with this object.
171  *
172  * @deprecated Use `Options` and `TracingComponentsOption`
173  */
174  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `TracingComponentsOption`")
175  ConnectionOptions& enable_tracing(std::string const& component) {
176  opts_.lookup<TracingComponentsOption>().insert(component);
177  return *this;
178  }
179 
180  /**
181  * Disable tracing for @p component in clients configured with this object.
182  *
183  * @deprecated Use `Options` and `TracingComponentsOption`
184  */
185  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `TracingComponentsOption`")
186  ConnectionOptions& disable_tracing(std::string const& component) {
187  opts_.lookup<TracingComponentsOption>().erase(component);
188  return *this;
189  }
190 
191  /**
192  * Return the set of tracing components.
193  *
194  * @deprecated Use `Options` and `TracingComponentsOption`
195  */
196  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `TracingComponentsOption`")
197  std::set<std::string> const& components() const {
199  }
200 
201  /**
202  * Return the options for use when tracing RPCs.
203  *
204  * @deprecated Use `Options` and `GrpcTracingOption`
205  */
206  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcTracingOption`")
209  }
210 
211  /**
212  * Define the gRPC channel domain for clients configured with this object.
213  *
214  * In some cases applications may want to use a separate gRPC connections for
215  * different clients. gRPC may share the connection used by separate channels
216  * created with the same configuration. The client objects created with this
217  * object will create gRPC channels configured with
218  * `grpc.channel_pooling_domain` set to the value returned by
219  * `channel_pool_domain()`. gRPC channels with different values for
220  * `grpc.channel_pooling_domain` are guaranteed to use different connections.
221  * Note that there is no guarantee that channels with the same value will have
222  * the same connection though.
223  *
224  * This option might be useful for applications that want to segregate traffic
225  * for whatever reason.
226  *
227  * @deprecated Use `Options` and `GrpcChannelsArgumentsOption`
228  */
229  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcChannelsArgumentOption`")
230  std::string const& channel_pool_domain() const {
231  return channel_pool_domain_;
232  }
233 
234  /**
235  * Set the value for `channel_pool_domain()`.
236  *
237  * @deprecated Use `Options` and `GrpcChannelsArgumentsOption`
238  */
239  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcChannelsArgumentsOption`")
240  ConnectionOptions& set_channel_pool_domain(std::string v) {
241  channel_pool_domain_ = std::move(v);
242  return *this;
243  }
244 
245  /**
246  * Prepend @p prefix to the user-agent string.
247  *
248  * Libraries or services that use Cloud C++ clients may want to set their own
249  * user-agent prefix. This can help them develop telemetry information about
250  * number of users running particular versions of their system or library.
251  *
252  * @deprecated Use `Options` and `UserAgentProductsOption`
253  */
254  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `UserAgentProductsOption`")
255  ConnectionOptions& add_user_agent_prefix(std::string prefix) {
256  prefix += " ";
257  prefix += user_agent_prefix_;
258  user_agent_prefix_ = std::move(prefix);
259  return *this;
260  }
261 
262  /**
263  * Return the current value for the user agent string.
264  *
265  * @deprecated Use `Options` and `UserAgentProductsOption`.
266  */
267  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `UserAgentProductsOption`")
268  std::string const& user_agent_prefix() const { return user_agent_prefix_; }
269 
270  /**
271  * Create a new `grpc::ChannelArguments` configured with the options in this
272  * object.
273  *
274  * The caller would typically pass this argument to
275  * `grpc::CreateCustomChannel` and create one more more gRPC channels.
276  *
277  * @deprecated Not intended for use in application code. There is
278  * no alternative implemented or planned.
279  */
280  GOOGLE_CLOUD_CPP_DEPRECATED(
281  "Not intended for use in application code. There is no alternative "
282  "implemented or planned.")
283  grpc::ChannelArguments CreateChannelArguments() const {
284  return internal::MakeChannelArguments(internal::MakeOptions(*this));
285  }
286 
287  /**
288  * Set the number of background threads.
289  *
290  * @note This value is not used if `DisableBackgroundThreads()` is called.
291  *
292  * @deprecated Use `Options` and `GrpcBackgroundThreadPoolSizeOption`
293  */
294  GOOGLE_CLOUD_CPP_DEPRECATED(
295  "Use `Options` and `GrpcBackgroundThreadPoolSizeOption`")
296  ConnectionOptions& set_background_thread_pool_size(std::size_t s) {
297  background_thread_pool_size_ = s;
298  return *this;
299  }
300 
301  /// @deprecated Use `Options` and `GrpcBackgroundThreadPoolSizeOption`.
302  GOOGLE_CLOUD_CPP_DEPRECATED(
303  "Use `Options` and `GrpcBackgroundThreadPoolSizeOption`")
304  std::size_t background_thread_pool_size() const {
305  return background_thread_pool_size_;
306  }
307 
308  /**
309  * Configure the connection to use @p cq for all background work.
310  *
311  * Connections need to perform background work on behalf of the application.
312  * Normally they just create a background thread and a `CompletionQueue` for
313  * this work, but the application may need more fine-grained control of their
314  * threads. In this case the application can provide the `CompletionQueue` and
315  * it assumes responsibility for creating one or more threads blocked on
316  * `CompletionQueue::Run()`.
317  *
318  * @deprecated Use `Options` and `GrpcCompletionQueueOption`
319  */
320  GOOGLE_CLOUD_CPP_DEPRECATED("Use `Options` and `GrpcCompletionQueueOption`")
321  ConnectionOptions& DisableBackgroundThreads(
322  google::cloud::CompletionQueue const& cq) {
323  background_threads_factory_ = [cq] {
324  return absl::make_unique<internal::CustomerSuppliedBackgroundThreads>(cq);
325  };
326  return *this;
327  }
328 
329  /// @deprecated Prefer using `::google::cloud::BackgroundThreadsFactory`.
330  using BackgroundThreadsFactory = ::google::cloud::BackgroundThreadsFactory;
331 
332  /// @deprecated Not intended for applications to use. There is no alternative
333  /// implemented or planned.
334  GOOGLE_CLOUD_CPP_DEPRECATED(
335  "Not intended for applications to use. There is no alternative "
336  "implemented or planned")
337  BackgroundThreadsFactory background_threads_factory() const {
338  if (background_threads_factory_) return background_threads_factory_;
339  auto const s = background_thread_pool_size_;
340  return [s] { return internal::DefaultBackgroundThreads(s); };
341  }
342 
343  private:
344  template <typename T>
345  friend Options internal::MakeOptions(ConnectionOptions<T>);
346 
347  Options opts_;
348 
349  // These are fields that have different semantics than the equivalent ones in
350  // the new `Options` class.
351  std::string user_agent_prefix_;
352  std::string channel_pool_domain_;
353  std::size_t background_thread_pool_size_ = 0;
354  BackgroundThreadsFactory background_threads_factory_;
355 };
356 
357 namespace internal {
358 
359 // The following function is used in backwards compatibility code, disable
360 // deprecation warnings for it.
361 #include "google/cloud/internal/disable_deprecation_warnings.inc"
362 template <typename ConnectionTraits>
363 Options MakeOptions(ConnectionOptions<ConnectionTraits> old) {
364  Options opts = std::move(old.opts_);
365  opts.set<UserAgentProductsOption>({std::move(old.user_agent_prefix_)});
367  old.background_threads_factory());
368  if (!old.channel_pool_domain_.empty()) {
369  // To get a different channel pool one just needs to set any channel
370  // parameter to a different value. Newer versions of gRPC include a macro
371  // for this purpose (GRPC_ARG_CHANNEL_POOL_DOMAIN). As we are compiling
372  // against older versions in some cases, we use the actual value.
373  opts.set<GrpcChannelArgumentsOption>(
374  {{"grpc.channel_pooling_domain", std::move(old.channel_pool_domain_)}});
375  }
376  return opts;
377 }
378 #include "google/cloud/internal/diagnostics_pop.inc"
379 
380 } // namespace internal
381 
383 } // namespace cloud
384 } // namespace google
385 
386 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_CONNECTION_OPTIONS_H