Google Cloud Storage C++ Client  2.5.0
A C++ Client Library for Google Cloud Storage
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_STORAGE_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OPTIONS_H
17 
18 #include "google/cloud/storage/idempotency_policy.h"
19 #include "google/cloud/storage/oauth2/credentials.h"
20 #include "google/cloud/storage/retry_policy.h"
21 #include "google/cloud/storage/version.h"
22 #include "google/cloud/backoff_policy.h"
23 #include "google/cloud/credentials.h"
24 #include "google/cloud/options.h"
25 #include <chrono>
26 #include <cstdint>
27 #include <memory>
28 #include <string>
29 
30 namespace google {
31 namespace cloud {
32 namespace storage_experimental {
34 
35 /**
36  * Set the HTTP version used by the client.
37  *
38  * If this option is not provided, or is set to `default` then the library uses
39  * [libcurl's default], typically HTTP/2 with SSL. Possible settings include:
40  * - "1.0": use HTTP/1.0, this is not recommended as would require a new
41  * connection for each request.
42  * - "1.1": use HTTP/1.1, this may be useful when the overhead of HTTP/2 is
43  * unacceptable. Note that this may require additional connections.
44  * - "2TLS": use HTTP/2 with TLS
45  * - "2.0": use HTTP/2 with our without TLS.
46  *
47  * [libcurl's default]: https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
48  *
49  * @ingroup storage-options
50  */
52  using Type = std::string;
53 };
54 
56 } // namespace storage_experimental
57 
58 namespace storage {
60 namespace internal {
61 /// This is only intended for testing against staging or development versions
62 /// of the service. It is not for public use.
63 struct TargetApiVersionOption {
64  using Type = std::string;
65 };
66 
67 /// This is only intended for testing. It is not for public use.
68 struct CAPathOption {
69  using Type = std::string;
70 };
71 
72 /// This is only intended for testing of the library. Not for public use.
73 struct UseRestClientOption {
74  using Type = bool;
75 };
76 
77 } // namespace internal
78 
79 /**
80  * Configure the REST endpoint for the GCS client library.
81  *
82  * @ingroup storage-options
83  */
85  using Type = std::string;
86 };
87 
88 /**
89  * Configure the IAM endpoint for the GCS client library.
90  *
91  * @ingroup storage-options
92  */
94  using Type = std::string;
95 };
96 
97 /**
98  * Configure oauth2::Credentials for the GCS client library.
99  *
100  * @ingroup storage-options
101  */
103  using Type = std::shared_ptr<oauth2::Credentials>;
104 };
105 
106 /**
107  * Set the Google Cloud Platform project id.
108  *
109  * @ingroup storage-options
110  */
112  using Type = std::string;
113 };
114 
115 /**
116  * Set the maximum connection pool size.
117  *
118  * The C++ client library uses this value to limit the growth of the
119  * connection pool. Once an operation (a RPC or a download) completes the
120  * connection used for that operation is returned to the pool. If the pool is
121  * full one or more connections are released. Otherwise, the connection is
122  * cached for use in following RPCs or downloads.
123  *
124  * @note Setting this value to 0 disables connection pooling.
125  *
126  * @warning The behavior of the connection pool may change in the future, only
127  * the maximum number of handles in use can be controlled by the application.
128  * The information about which handles are released and when is for
129  * informational purposes only.
130  *
131  * The library does not create connections proactively, setting a high value
132  * may result in very few connections if your application does not need them.
133  * The library may create more connections than this option configures, for
134  * example if your application requests many simultaneous downloads. When the
135  * pool is full, the library typically releases older connections first, and
136  * tries to reuse newer connections if they are available. The library may
137  * release more than one connection when the pool becomes full.
138  *
139  * @ingroup storage-options
140  */
142  using Type = std::size_t;
143 };
144 
145 /**
146  * Control the formatted I/O download buffer.
147  *
148  * When using formatted I/O operations (typically `operator>>(std::istream&...)`
149  * this option controls the size of the in-memory buffer kept to satisfy any I/O
150  * requests.
151  *
152  * Applications seeking optimal performance for downloads should avoid
153  * formatted I/O, and prefer using `std::istream::read()`. This option has no
154  * effect in that case.
155  *
156  * @ingroup storage-options
157  */
159  using Type = std::size_t;
160 };
161 
162 /**
163  * Control the formatted I/O upload buffer.
164  *
165  * When using formatted I/O operations (typically `operator<<(std::istream&...)`
166  * this option controls the size of the in-memory buffer kept before a chunk is
167  * uploaded. Note that GCS only accepts chunks in multiples of 256KiB, so this
168  * option is always rounded up to the next such multiple.
169  *
170  * Applications seeking optimal performance for downloads should avoid
171  * formatted I/O, and prefer using `std::istream::write()`. This option has no
172  * effect in that case.
173  *
174  * @ingroup storage-options
175  */
177  using Type = std::size_t;
178 };
179 
180 /**
181  * Defines the threshold to switch from simple to resumable uploads for files.
182  *
183  * When uploading small files the faster approach is to use a simple upload. For
184  * very large files this is not feasible, as the whole file may not fit in
185  * memory (we are ignoring memory mapped files in this discussion). The library
186  * automatically switches to resumable upload for files larger than this
187  * threshold.
188  *
189  * @ingroup storage-options
190  */
192  using Type = std::size_t;
193 };
194 
195 /**
196  * Disables automatic OpenSSL locking.
197  *
198  * With older versions of OpenSSL any locking must be provided by locking
199  * callbacks in the application or intermediate libraries. The C++ client
200  * library automatically provides the locking callbacks. If your application
201  * already provides such callbacks, and you prefer to use them, set this option
202  * to `false`.
203  *
204  * @note This option is only useful for applications linking against
205  * OpenSSL 1.0.2.
206  */
208  using Type = bool;
209 };
210 
211 /**
212  * Disables automatic OpenSSL sigpipe handler.
213  *
214  * With some versions of OpenSSL it might be necessary to setup a SIGPIPE
215  * handler. If your application already provides such a handler, set this option
216  * to `false` to disable the handler in the GCS C++ client library.
217  */
219  using Type = bool;
220 };
221 
222 /**
223  * Control the maximum socket receive buffer.
224  *
225  * The default is to let the operating system pick a value. Applications that
226  * perform multiple downloads in parallel may need to use smaller receive
227  * buffers to avoid exhausting the OS resources dedicated to TCP buffers.
228  */
230  using Type = std::size_t;
231 };
232 
233 /**
234  * Control the maximum socket send buffer.
235  *
236  * The default is to let the operating system pick a value, this is almost
237  * always a good choice.
238  */
240  using Type = std::size_t;
241 };
242 
243 /**
244  * Sets the transfer stall timeout.
245  *
246  * If a transfer (upload, download, or request) *stalls*, i.e., no bytes are
247  * sent or received for a significant period, it may be better to restart the
248  * transfer as this may indicate a network glitch. For downloads the
249  * google::cloud::storage::DownloadStallTimeoutOption takes precedence.
250  *
251  * For large requests (e.g. downloads in the GiB to TiB range) this is a better
252  * configuration parameter than a simple timeout, as the transfers will take
253  * minutes or hours to complete. Relying on a timeout value for them would not
254  * work, as the timeout would be too large to be useful. For small requests,
255  * this is as effective as a timeout parameter, but maybe unfamiliar and thus
256  * harder to reason about.
257  *
258  * @ingroup storage-options
259  */
261  using Type = std::chrono::seconds;
262 };
263 
264 /**
265  * The minimum accepted bytes/second transfer rate.
266  *
267  * If the average rate is below this value for the `TransferStallTimeoutOption`
268  * then the transfer is aborted.
269  *
270  * @ingroup storage-options
271  */
273  using Type = std::int32_t;
274 };
275 
276 /**
277  * Sets the download stall timeout.
278  *
279  * If a download *stalls*, i.e., no bytes are received for a significant period,
280  * it may be better to restart the download as this may indicate a network
281  * glitch.
282  *
283  * For large requests (e.g. downloads in the GiB to TiB range) this is a better
284  * configuration parameter than a simple timeout, as the transfers will take
285  * minutes or hours to complete. Relying on a timeout value for them would not
286  * work, as the timeout would be too large to be useful. For small requests,
287  * this is as effective as a timeout parameter, but maybe unfamiliar and thus
288  * harder to reason about.
289  *
290  * @ingroup storage-options
291  */
293  using Type = std::chrono::seconds;
294 };
295 
296 /**
297  * The minimum accepted bytes/second download rate.
298  *
299  * If the average rate is below this value for the `DownloadStallTimeoutOption`
300  * then the download is aborted.
301  *
302  * @ingroup storage-options
303  */
305  using Type = std::int32_t;
306 };
307 
308 /**
309  * Set the retry policy for a GCS client.
310  *
311  * @ingroup storage-options
312  */
314  using Type = std::shared_ptr<RetryPolicy>;
315 };
316 
317 /**
318  * Set the backoff policy for a GCS client.
319  *
320  * @ingroup storage-options
321  */
323  using Type = std::shared_ptr<BackoffPolicy>;
324 };
325 
326 /**
327  * Set the idempotency policy for a GCS client.
328  *
329  * @ingroup storage-options
330  */
332  using Type = std::shared_ptr<IdempotencyPolicy>;
333 };
334 
335 /// The complete list of options accepted by `storage::Client`.
336 using ClientOptionList = ::google::cloud::OptionList<
345 
347 } // namespace storage
348 } // namespace cloud
349 } // namespace google
350 
351 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OPTIONS_H