Google Cloud Storage C++ Client  1.32.1
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 // 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_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 <memory>
27 #include <string>
28 
29 namespace google {
30 namespace cloud {
31 namespace storage_experimental {
32 inline namespace STORAGE_CLIENT_NS {
33 /**
34  * Set the HTTP version used by the client.
35  *
36  * If this option is not provided, or is set to `default` then the library uses
37  * [libcurl's default], typically HTTP/2 with SSL. Possible settings include:
38  * - "1.0": use HTTP/1.0, this is not recommended as would require a new
39  * connection for each request.
40  * - "1.1": use HTTP/1.1, this may be useful when the overhead of HTTP/2 is
41  * unacceptable. Note that this may require additional connections.
42  * - "2TLS": use HTTP/2 with TLS
43  * - "2.0": use HTTP/2 with our without TLS.
44  *
45  * [libcurl's default]: https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
46  */
48  using Type = std::string;
49 };
50 } // namespace STORAGE_CLIENT_NS
51 } // namespace storage_experimental
52 
53 namespace storage {
54 inline namespace STORAGE_CLIENT_NS {
55 namespace internal {
56 /// This is only intended for testing against staging or development versions
57 /// of the service. It is not for public use.
58 struct TargetApiVersionOption {
59  using Type = std::string;
60 };
61 
62 /// This is only intended for testing. It is not for public use.
63 struct CAPathOption {
64  using Type = std::string;
65 };
66 
67 } // namespace internal
68 
69 /// Configure the REST endpoint for the GCS client library.
71  using Type = std::string;
72 };
73 
74 /// Configure the IAM endpoint for the GCS client library.
76  using Type = std::string;
77 };
78 
79 /// Configure oauth2::Credentials for the GCS client library.
81  using Type = std::shared_ptr<oauth2::Credentials>;
82 };
83 
84 /// Set the Google Cloud Platform project id.
86  using Type = std::string;
87 };
88 
89 /**
90  * Set the maximum connection pool size.
91  *
92  * The C++ client library uses this value to limit the growth of the
93  * connection pool. Once an operation (a RPC or a download) completes the
94  * connection used for that operation is returned to the pool. If the pool is
95  * full the connection is immediately released. If the pool has room the
96  * connection is cached for the next RPC or download.
97  *
98  * @note The behavior of this pool may change in the future, depending on the
99  * low-level implementation details of the library.
100  *
101  * @note The library does not create connections proactively, setting a high
102  * value may result in very few connections if your application does not need
103  * them.
104  *
105  * @warning The library may create more connections than this option configures,
106  * for example if your application requests many simultaneous downloads.
107  */
109  using Type = std::size_t;
110 };
111 
112 /**
113  * Control the formatted I/O download buffer.
114  *
115  * When using formatted I/O operations (typically `operator>>(std::istream&...)`
116  * this option controls the size of the in-memory buffer kept to satisfy any I/O
117  * requests.
118  *
119  * Applications seeking optional performance for downloads should avoid
120  * formatted I/O, and prefer using `std::istream::read()`. This option has no
121  * effect in that case.
122  */
124  using Type = std::size_t;
125 };
126 
127 /**
128  * Control the formatted I/O upload buffer.
129  *
130  * When using formatted I/O operations (typically `operator<<(std::istream&...)`
131  * this option controls the size of the in-memory buffer kept before a chunk is
132  * uploaded. Note that GCS only accepts chunks in multiples of 256KiB, so this
133  * option is always rounded up to the next such multiple.
134  *
135  * Applications seeking optional performance for downloads should avoid
136  * formatted I/O, and prefer using `std::istream::write()`. This option has no
137  * effect in that case.
138  */
140  using Type = std::size_t;
141 };
142 
143 /**
144  * Defines the threshold to switch from simple to resumable uploads for files.
145  *
146  * When uploading small files the faster approach is to use a simple upload. For
147  * very large files this is not feasible, as the whole file may not fit in
148  * memory (we are ignoring memory mapped files in this discussion). The library
149  * automatically switches to resumable upload for files larger than this
150  * threshold.
151  */
153  using Type = std::size_t;
154 };
155 
156 /**
157  * Disables automatic OpenSSL locking.
158  *
159  * With older versions of OpenSSL any locking must be provided by locking
160  * callbacks in the application or intermediate libraries. The C++ client
161  * library automatically provides the locking callbacks. If your application
162  * already provides such callbacks, and you prefer to use them, set this option
163  * to `false`.
164  *
165  * @note This option is only useful for applications linking against
166  * OpenSSL 1.0.2.
167  */
169  using Type = bool;
170 };
171 
172 /**
173  * Disables automatic OpenSSL sigpipe handler.
174  *
175  * With some versions of OpenSSL it might be necessary to setup a SIGPIPE
176  * handler. If your application already provides such a handler, set this option
177  * to `false` to disable the handler in the GCS C++ client library.
178  */
180  using Type = bool;
181 };
182 
183 /**
184  * Control the maximum socket receive buffer.
185  *
186  * The default is to let the operating system pick a value. Applications that
187  * perform multiple downloads in parallel may need to use smaller receive
188  * buffers to avoid exhausting the OS resources dedicated to TCP buffers.
189  */
191  using Type = std::size_t;
192 };
193 
194 /**
195  * Control the maximum socket send buffer.
196  *
197  * The default is to let the operating system pick a value, this is almost
198  * always a good choice.
199  */
201  using Type = std::size_t;
202 };
203 
204 /**
205  * Sets the transfer stall timeout.
206  *
207  * If a transfer (upload, download, or request) *stalls*, i.e., no bytes are
208  * sent or received for a significant period, it may be better to restart the
209  * transfer as this may indicate a network glitch.
210  *
211  * For large requests (e.g. downloads in the GiB to TiB range) this is a better
212  * configuration parameter than a simple timeout, as the transfers will take
213  * minutes or hours to complete. Relying on a timeout value for them would not
214  * work, as the timeout would be too large to be useful. For small requests,
215  * this is as effective as a timeout parameter, but maybe unfamiliar and thus
216  * harder to reason about.
217  */
219  using Type = std::chrono::seconds;
220 };
221 
222 /**
223  * @deprecated Please use TransferStallTimeoutOption instead
224  */
225 using DownloadStallTimeoutOption = TransferStallTimeoutOption;
226 
227 /// Set the retry policy for a GCS client.
229  using Type = std::shared_ptr<RetryPolicy>;
230 };
231 
232 /// Set the backoff policy for a GCS client.
234  using Type = std::shared_ptr<BackoffPolicy>;
235 };
236 
237 /// Set the idempotency policy for a GCS client.
239  using Type = std::shared_ptr<IdempotencyPolicy>;
240 };
241 
242 /// The complete list of options accepted by `storage::Client`.
243 using ClientOptionList = ::google::cloud::OptionList<
252 
253 } // namespace STORAGE_CLIENT_NS
254 } // namespace storage
255 } // namespace cloud
256 } // namespace google
257 
258 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OPTIONS_H