Google Cloud Spanner C++ Client  2.1.0
A C++ Client Library for Google Cloud Spanner
read_partition.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 // 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_READ_PARTITION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_READ_PARTITION_H
17 
18 #include "google/cloud/spanner/connection.h"
19 #include "google/cloud/spanner/keys.h"
20 #include "google/cloud/spanner/version.h"
21 #include "google/cloud/status_or.h"
22 #include <google/spanner/v1/spanner.pb.h>
23 #include <string>
24 #include <vector>
25 
26 namespace google {
27 namespace cloud {
28 namespace spanner_internal {
30 class ReadPartitionTester;
31 struct ReadPartitionInternals;
33 } // namespace spanner_internal
34 
35 namespace spanner {
37 
38 /**
39  * Serializes an instance of `ReadPartition` to a string of bytes.
40  *
41  * The serialized string of bytes is suitable for writing to disk or
42  * transmission to another process.
43  *
44  * @note The serialized string may contain NUL and other non-printable
45  * characters. Therefore, callers should avoid [formatted IO][formatted-io]
46  * functions that may incorrectly reformat the string data.
47  *
48  * @param read_partition - instance to be serialized.
49  *
50  * @par Example
51  * @snippet samples.cc serialize-read-partition
52  *
53  * [formatted-io]:
54  * https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt
55  */
56 StatusOr<std::string> SerializeReadPartition(
57  ReadPartition const& read_partition);
58 
59 /**
60  * Deserializes the provided string into a `ReadPartition`.
61  *
62  * The @p serialized_read_partition argument must be a string that was
63  * previously returned by a call to `SerializeReadPartition()`.
64  *
65  * @note The serialized string may contain NUL and other non-printable
66  * characters. Therefore, callers should avoid [formatted IO][formatted-io]
67  * functions that may incorrectly reformat the string data.
68  *
69  * @param serialized_read_partition - string representation to be deserialized.
70  *
71  * @par Example
72  * @snippet samples.cc deserialize-read-partition
73  *
74  * [formatted-io]:
75  * https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt
76  */
78  std::string const& serialized_read_partition);
79 
80 /**
81  * The `ReadPartition` class is a regular type that represents a single
82  * slice of a parallel Read operation.
83  *
84  * Instances of `ReadPartition` are created by `Client::PartitionRead`. Once
85  * created, `ReadPartition` objects can be serialized, transmitted to separate
86  * process, and used to read data in parallel using `Client::Read`.
87  */
89  public:
90  /**
91  * Constructs an instance of `ReadPartition` that does not specify any table
92  * or columns to be read.
93  */
94  ReadPartition() = default;
95 
96  /// @name Copy and move.
97  ///@{
98  ReadPartition(ReadPartition const&) = default;
100  ReadPartition& operator=(ReadPartition const&) = default;
102  ///@}
103 
104  std::string TableName() const { return proto_.table(); }
105 
106  std::vector<std::string> ColumnNames() const {
107  auto const& columns = proto_.columns();
108  return std::vector<std::string>(columns.begin(), columns.end());
109  }
110 
111  google::cloud::spanner::ReadOptions ReadOptions() const;
112 
113  /// @name Equality
114  ///@{
115  friend bool operator==(ReadPartition const& lhs, ReadPartition const& rhs);
116  friend bool operator!=(ReadPartition const& lhs, ReadPartition const& rhs);
117  ///@}
118 
119  private:
120  friend class spanner_internal::ReadPartitionTester;
121  friend struct spanner_internal::ReadPartitionInternals;
122  friend StatusOr<std::string> SerializeReadPartition(
123  ReadPartition const& read_partition);
125  std::string const& serialized_read_partition);
126 
127  explicit ReadPartition(google::spanner::v1::ReadRequest proto)
128  : proto_(std::move(proto)) {}
129  ReadPartition(std::string transaction_id, std::string transaction_tag,
130  std::string session_id, std::string partition_token,
131  std::string table_name, google::cloud::spanner::KeySet key_set,
132  std::vector<std::string> column_names,
133  google::cloud::spanner::ReadOptions read_options);
134 
135  // Accessor methods for use by friends.
136  std::string PartitionToken() const { return proto_.partition_token(); }
137  std::string SessionId() const { return proto_.session(); }
138  std::string TransactionId() const { return proto_.transaction().id(); }
139  std::string TransactionTag() const {
140  return proto_.request_options().transaction_tag();
141  }
142  google::spanner::v1::KeySet KeySet() const { return proto_.key_set(); }
143 
144  google::spanner::v1::ReadRequest proto_;
145 };
146 
148 } // namespace spanner
149 
150 // Internal implementation details that callers should not use.
151 namespace spanner_internal {
153 
154 struct ReadPartitionInternals {
155  static spanner::ReadPartition MakeReadPartition(
156  std::string transaction_id, std::string transaction_tag,
157  std::string session_id, std::string partition_token,
158  std::string table_name, spanner::KeySet key_set,
159  std::vector<std::string> column_names,
160  spanner::ReadOptions read_options) {
161  return spanner::ReadPartition(
162  std::move(transaction_id), std::move(transaction_tag),
163  std::move(session_id), std::move(partition_token),
164  std::move(table_name), std::move(key_set), std::move(column_names),
165  std::move(read_options));
166  }
167 
168  static spanner::Connection::ReadParams MakeReadParams(
169  spanner::ReadPartition const& read_partition) {
170  return spanner::Connection::ReadParams{
171  MakeTransactionFromIds(read_partition.SessionId(),
172  read_partition.TransactionId(),
173  read_partition.TransactionTag()),
174  read_partition.TableName(),
175  FromProto(read_partition.KeySet()),
176  read_partition.ColumnNames(),
177  read_partition.ReadOptions(),
178  read_partition.PartitionToken()};
179  }
180 };
181 
182 inline spanner::ReadPartition MakeReadPartition(
183  std::string transaction_id, std::string transaction_tag,
184  std::string session_id, std::string partition_token, std::string table_name,
185  spanner::KeySet key_set, std::vector<std::string> column_names,
186  spanner::ReadOptions read_options) {
187  return ReadPartitionInternals::MakeReadPartition(
188  std::move(transaction_id), std::move(transaction_tag),
189  std::move(session_id), std::move(partition_token), std::move(table_name),
190  std::move(key_set), std::move(column_names), std::move(read_options));
191 }
192 
193 inline spanner::Connection::ReadParams MakeReadParams(
194  spanner::ReadPartition const& read_partition) {
195  return ReadPartitionInternals::MakeReadParams(read_partition);
196 }
197 
199 } // namespace spanner_internal
200 } // namespace cloud
201 } // namespace google
202 
203 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_READ_PARTITION_H