Google Cloud Spanner C++ Client  2.5.0
A C++ Client Library for Google Cloud Spanner
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_SPANNER_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_OPTIONS_H
17 
18 /**
19  * @file
20  *
21  * This file defines options to be used with instances of
22  * `google::cloud::Options`. By convention options are named with an "Option"
23  * suffix. As the name would imply, all options are optional, and leaving them
24  * unset will result in a reasonable default being chosen.
25  *
26  * Not all options are meaningful to all functions that accept a
27  * `google::cloud::Options` instance. Each function that accepts a
28  * `google::cloud::Options` should document which options it expects. This is
29  * typically done by indicating lists of options using "OptionList" aliases.
30  * For example, a function may indicate that users may set any option in
31  * `SpannerPolicyOptionList`.
32  *
33  * @note Unrecognized options are allowed and will be ignored. To debug issues
34  * with options set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment
35  * and unexpected options will be logged.
36  *
37  * @see `google::cloud::CommonOptionList`
38  * @see `google::cloud::GrpcOptionList`
39  */
40 
41 #include "google/cloud/spanner/backoff_policy.h"
42 #include "google/cloud/spanner/internal/session.h"
43 #include "google/cloud/spanner/polling_policy.h"
44 #include "google/cloud/spanner/request_priority.h"
45 #include "google/cloud/spanner/retry_policy.h"
46 #include "google/cloud/spanner/version.h"
47 #include "google/cloud/options.h"
48 #include <chrono>
49 #include <cstddef>
50 #include <cstdint>
51 #include <map>
52 #include <memory>
53 
54 namespace google {
55 namespace cloud {
56 namespace spanner {
58 
59 /**
60  * Option for `google::cloud::Options` to set a `spanner::RetryPolicy`.
61  *
62  * @ingroup spanner-options
63  */
65  using Type = std::shared_ptr<spanner::RetryPolicy>;
66 };
67 
68 /**
69  * Option for `google::cloud::Options` to set a `spanner::BackoffPolicy`.
70  *
71  * @ingroup spanner-options
72  */
74  using Type = std::shared_ptr<spanner::BackoffPolicy>;
75 };
76 
77 /**
78  * Option for `google::cloud::Options` to set a `spanner::PollingPolicy`.
79  *
80  * @ingroup spanner-options
81  */
83  using Type = std::shared_ptr<spanner::PollingPolicy>;
84 };
85 
86 /**
87  * List of all "policy" options.
88  */
89 using SpannerPolicyOptionList =
92 
93 /**
94  * Option for `google::cloud::Options` to set the database role used for
95  * session creation.
96  *
97  * @ingroup spanner-options
98  */
100  using Type = std::string;
101 };
102 
103 /**
104  * Option for `google::cloud::Options` to set the minimum number of sessions to
105  * keep in the pool.
106  *
107  * Values <= 0 are treated as 0.
108  * This value will effectively be reduced if it exceeds the overall limit on
109  * the number of sessions (`max_sessions_per_channel` * number of channels).
110  *
111  * @ingroup spanner-options
112  */
114  using Type = int;
115 };
116 
117 /**
118  * Option for `google::cloud::Options` to set the maximum number of sessions to
119  * create on each channel.
120  *
121  * Values <= 1 are treated as 1.
122  *
123  * @ingroup spanner-options
124  */
126  using Type = int;
127 };
128 
129 /**
130  * Option for `google::cloud::Options` to set the maximum number of sessions to
131  * keep in the pool in an idle state.
132  *
133  * Values <= 0 are treated as 0.
134  *
135  * @ingroup spanner-options
136  */
138  using Type = int;
139 };
140 
141 /// Action to take when the session pool is exhausted.
143 /**
144  * Option for `google::cloud::Options` to set the action to take when
145  * attempting to allocate a session when the pool is exhausted.
146  *
147  * @ingroup spanner-options
148  */
151 };
152 
153 /**
154  * Option for `google::cloud::Options` to set the interval at which we refresh
155  * sessions so they don't get collected by the backend GC.
156  *
157  * The GC collects objects older than 60 minutes, so any duration
158  * below that (less some slack to allow the calls to be made to refresh the
159  * sessions) should suffice.
160  *
161  * @ingroup spanner-options
162  */
164  using Type = std::chrono::seconds;
165 };
166 
167 /**
168  * Option for `google::cloud::Options` to set the labels used when creating
169  * sessions within the pool.
170  *
171  * * Label keys must match `[a-z]([-a-z0-9]{0,61}[a-z0-9])?`.
172  * * Label values must match `([a-z]([-a-z0-9]{0,61}[a-z0-9])?)?`.
173  * * The maximum number of labels is 64.
174  *
175  * @ingroup spanner-options
176  */
178  using Type = std::map<std::string, std::string>;
179 };
180 
181 /**
182  * List of all SessionPool options. Pass to `spanner::MakeConnection()`.
183  */
184 using SessionPoolOptionList =
190 
191 /**
192  * Option for `google::cloud::Options` to set the optimizer version used in an
193  * SQL query.
194  *
195  * @ingroup spanner-options
196  */
198  using Type = std::string;
199 };
200 
201 /**
202  * Option for `google::cloud::Options` to set the optimizer statistics package
203  * used in an SQL query.
204  *
205  * @ingroup spanner-options
206  */
208  using Type = std::string;
209 };
210 
211 /**
212  * Option for `google::cloud::Options` to set a `spanner::RequestPriority`.
213  *
214  * @ingroup spanner-options
215  */
217  using Type = spanner::RequestPriority;
218 };
219 
220 /**
221  * Option for `google::cloud::Options` to set a per-request tag.
222  *
223  * @ingroup spanner-options
224  */
226  using Type = std::string;
227 };
228 
229 /**
230  * Option for `google::cloud::Options` to set the name of an index on a
231  * database table. This index is used instead of the table primary key when
232  * interpreting the `KeySet` and sorting result rows.
233  *
234  * @ingroup spanner-options
235  */
237  using Type = std::string;
238 };
239 
240 /**
241  * Option for `google::cloud::Options` to set a limit on the number of rows
242  * to yield from `Client::Read()`. There is no limit when the option is unset,
243  * or when it is set to 0.
244  *
245  * @ingroup spanner-options
246  */
248  using Type = std::int64_t;
249 };
250 
251 /**
252  * Option for `google::cloud::Options` to set a limit on how much data will
253  * be buffered to guarantee resumability of a streaming read or SQL query.
254  * If the limit is exceeded, and the stream is subsequently interrupted before
255  * a new resumption point can be established, the read/query will fail.
256  *
257  * @ingroup spanner-options
258  */
260  using Type = std::size_t;
261 };
262 
263 /**
264  * Option for `google::cloud::Options` to set the desired partition size to
265  * be generated by `Client::PartitionRead()` or `PartitionQuery()`.
266  *
267  * The default for this option is currently 1 GiB. This is only a hint. The
268  * actual size of each partition may be smaller or larger than this request.
269  *
270  * @ingroup spanner-options
271  */
273  using Type = std::int64_t;
274 };
275 
276 /**
277  * Option for `google::cloud::Options` to set the desired maximum number of
278  * partitions to return from `Client::PartitionRead()` or `PartitionQuery()`.
279  *
280  * For example, this may be set to the number of workers available. The
281  * default for this option is currently 10,000. The maximum value is
282  * currently 200,000. This is only a hint. The actual number of partitions
283  * returned may be smaller or larger than this request.
284  *
285  * @ingroup spanner-options
286  */
288  using Type = std::int64_t;
289 };
290 
291 /**
292  * Option for `google::cloud::Options` to set a per-transaction tag.
293  *
294  * @ingroup spanner-options
295  */
297  using Type = std::string;
298 };
299 
300 /**
301  * Option for `google::cloud::Options` to return additional statistics
302  * about the committed transaction in a `spanner::CommitResult`.
303  *
304  * @ingroup spanner-options
305  */
307  using Type = bool;
308 };
309 
310 /**
311  * List of Request options for `client::ExecuteBatchDml()`.
312  */
313 using RequestOptionList = OptionList<RequestPriorityOption, RequestTagOption>;
314 
316 } // namespace spanner
317 } // namespace cloud
318 } // namespace google
319 
320 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_OPTIONS_H