Google Cloud Spanner C++ Client  1.32.1
A C++ Client Library for Google Cloud Spanner
session_pool_options.h
Go to the documentation of this file.
1 // Copyright 2019 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_SESSION_POOL_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_SESSION_POOL_OPTIONS_H
17 
18 #include "google/cloud/spanner/internal/defaults.h"
19 #include "google/cloud/spanner/options.h"
20 #include "google/cloud/spanner/version.h"
21 #include "google/cloud/grpc_options.h"
22 #include <algorithm>
23 #include <chrono>
24 #include <map>
25 #include <string>
26 
27 namespace google {
28 namespace cloud {
29 namespace spanner {
30 inline namespace SPANNER_CLIENT_NS {
31 class SessionPoolOptions;
32 } // namespace SPANNER_CLIENT_NS
33 } // namespace spanner
34 
35 namespace spanner_internal {
36 inline namespace SPANNER_CLIENT_NS {
37 Options MakeOptions(spanner::SessionPoolOptions);
38 } // namespace SPANNER_CLIENT_NS
39 } // namespace spanner_internal
40 
41 namespace spanner {
42 inline namespace SPANNER_CLIENT_NS {
43 
44 /**
45  * Controls the session pool maintained by a `spanner::Client`.
46  *
47  * Creating Cloud Spanner sessions is an expensive operation. The
48  * [recommended practice][spanner-sessions-doc] is to maintain a cache (or pool)
49  * of sessions in the client side. This class controls the initial size of this
50  * pool, and how the pool grows (or shrinks) as needed.
51  *
52  * @note If no sessions are available to perform an operation the client library
53  * blocks until new sessions are available (either released by other threads
54  * or allocated on-demand, depending on the active constraints). It is
55  * also possible to configure the client to fail a request when the session
56  * pool is exhausted.
57  *
58  * [spanner-sessions-doc]: https://cloud.google.com/spanner/docs/sessions
59  */
61  public:
62  SessionPoolOptions() : opts_(spanner_internal::DefaultOptions()) {}
63 
64  /**
65  * Enforce the stated constraints on the option values, altering them if
66  * necessary. This can't be done in the setters, since we don't yet know
67  * the number of channels, and it would also constrain the order in which
68  * the fields must be set.
69  *
70  * @p num_channels the number of RPC channels in use by the pool.
71  */
73  opts_.set<GrpcNumChannelsOption>(num_channels);
74  opts_ = spanner_internal::DefaultOptions(std::move(opts_));
75  return *this;
76  }
77 
78  /**
79  * Set the minimum number of sessions to keep in the pool.
80  * Values <= 0 are treated as 0.
81  * This value will effectively be reduced if it exceeds the overall limit on
82  * the number of sessions (`max_sessions_per_channel` * number of channels).
83  */
86  return *this;
87  }
88 
89  /// Return the minimum number of sessions to keep in the pool.
91 
92  /**
93  * Set the maximum number of sessions to create on each channel.
94  * Values <= 1 are treated as 1.
95  */
98  return *this;
99  }
100 
101  /// Return the minimum number of sessions to keep in the pool.
104  }
105 
106  /**
107  * Set the maximum number of sessions to keep in the pool in an idle state.
108  * Values <= 0 are treated as 0.
109  */
112  return *this;
113  }
114 
115  /// Return the maximum number of idle sessions to keep in the pool.
116  int max_idle_sessions() const {
118  }
119 
120  /// Set whether to block or fail on pool exhaustion.
122  opts_.set<SessionPoolActionOnExhaustionOption>(std::move(action));
123  return *this;
124  }
125 
126  /**
127  * Return the action to take (kBlock or kFail) when attempting to allocate a
128  * session when the pool is exhausted.
129  */
132  }
133 
134  /**
135  * Set the interval at which we refresh sessions so they don't get
136  * collected by the backend GC. The GC collects objects older than 60
137  * minutes, so any duration below that (less some slack to allow the calls
138  * to be made to refresh the sessions) should suffice.
139  */
140  SessionPoolOptions& set_keep_alive_interval(std::chrono::seconds interval) {
141  opts_.set<SessionPoolKeepAliveIntervalOption>(std::move(interval));
142  return *this;
143  }
144 
145  /// Return the interval at which we refresh sessions to prevent GC.
146  std::chrono::seconds keep_alive_interval() const {
148  }
149 
150  /**
151  * Set the labels used when creating sessions within the pool.
152  * * Label keys must match `[a-z]([-a-z0-9]{0,61}[a-z0-9])?`.
153  * * Label values must match `([a-z]([-a-z0-9]{0,61}[a-z0-9])?)?`.
154  * * The maximum number of labels is 64.
155  */
156  SessionPoolOptions& set_labels(std::map<std::string, std::string> labels) {
157  opts_.set<SessionPoolLabelsOption>(std::move(labels));
158  return *this;
159  }
160 
161  /// Return the labels used when creating sessions within the pool.
162  std::map<std::string, std::string> const& labels() const {
164  }
165 
166  private:
167  friend Options spanner_internal::MakeOptions(SessionPoolOptions);
168  Options opts_;
169 };
170 
171 } // namespace SPANNER_CLIENT_NS
172 } // namespace spanner
173 
174 namespace spanner_internal {
175 inline namespace SPANNER_CLIENT_NS {
176 inline Options MakeOptions(spanner::SessionPoolOptions old) {
177  return std::move(old.opts_);
178 }
179 } // namespace SPANNER_CLIENT_NS
180 } // namespace spanner_internal
181 
182 } // namespace cloud
183 } // namespace google
184 
185 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_SESSION_POOL_OPTIONS_H