Google Cloud Spanner C++ Client  1.34.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 // 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_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 <map>
50 #include <memory>
51 
52 namespace google {
53 namespace cloud {
54 namespace spanner {
56 
57 /**
58  * Option for `google::cloud::Options` to set a `spanner::RetryPolicy`.
59  */
61  using Type = std::shared_ptr<spanner::RetryPolicy>;
62 };
63 
64 /**
65  * Option for `google::cloud::Options` to set a `spanner::BackoffPolicy`.
66  */
68  using Type = std::shared_ptr<spanner::BackoffPolicy>;
69 };
70 
71 /**
72  * Option for `google::cloud::Options` to set a `spanner::PollingPolicy`.
73  */
75  using Type = std::shared_ptr<spanner::PollingPolicy>;
76 };
77 
78 /**
79  * List of all "policy" options.
80  */
81 using SpannerPolicyOptionList =
84 
85 /**
86  * Option for `google::cloud::Options` to set the minimum number of sessions to
87  * keep in the pool.
88  *
89  * Values <= 0 are treated as 0.
90  * This value will effectively be reduced if it exceeds the overall limit on
91  * the number of sessions (`max_sessions_per_channel` * number of channels).
92  */
94  using Type = int;
95 };
96 
97 /**
98  * Option for `google::cloud::Options` to set the maximum number of sessions to
99  * create on each channel.
100  *
101  * Values <= 1 are treated as 1.
102  */
104  using Type = int;
105 };
106 
107 /**
108  * Option for `google::cloud::Options` to set the maximum number of sessions to
109  * keep in the pool in an idle state.
110  *
111  * Values <= 0 are treated as 0.
112  */
114  using Type = int;
115 };
116 
117 /// Action to take when the session pool is exhausted.
119 /**
120  * Option for `google::cloud::Options` to set the action to take when
121  * attempting to allocate a session when the pool is exhausted.
122  */
125 };
126 
127 /**
128  * Option for `google::cloud::Options` to set the interval at which we refresh
129  * sessions so they don't get collected by the backend GC.
130  *
131  * The GC collects objects older than 60 minutes, so any duration
132  * below that (less some slack to allow the calls to be made to refresh the
133  * sessions) should suffice.
134  */
136  using Type = std::chrono::seconds;
137 };
138 
139 /**
140  * Option for `google::cloud::Options` to set the labels used when creating
141  * sessions within the pool.
142  *
143  * * Label keys must match `[a-z]([-a-z0-9]{0,61}[a-z0-9])?`.
144  * * Label values must match `([a-z]([-a-z0-9]{0,61}[a-z0-9])?)?`.
145  * * The maximum number of labels is 64.
146  */
148  using Type = std::map<std::string, std::string>;
149 };
150 
151 /**
152  * List of all SessionPool options.
153  */
154 using SessionPoolOptionList = OptionList<
158 
159 /**
160  * Option for `google::cloud::Options` to set a `spanner::RequestPriority`.
161  */
163  using Type = spanner::RequestPriority;
164 };
165 
166 /**
167  * Option for `google::cloud::Options` to set a per-request tag.
168  */
170  using Type = std::string;
171 };
172 
173 /**
174  * List of all Request options.
175  */
176 using RequestOptionList = OptionList<RequestPriorityOption, RequestTagOption>;
177 
179 } // namespace spanner
180 } // namespace cloud
181 } // namespace google
182 
183 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_OPTIONS_H