Google Cloud Storage C++ Client  1.34.0
A C++ Client Library for Google Cloud Storage
object_rewriter.h
Go to the documentation of this file.
1 // Copyright 2018 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_OBJECT_REWRITER_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_REWRITER_H
17 
18 #include "google/cloud/storage/internal/raw_client.h"
19 #include "google/cloud/storage/version.h"
20 #include "google/cloud/internal/invoke_result.h"
21 #include <string>
22 
23 namespace google {
24 namespace cloud {
25 namespace storage {
27 /**
28  * Represents the status of a rewrite operation.
29  *
30  * The ObjectRewrite class may require multiple calls to `Iterate()` to finish
31  * the copy. This class represents the progress in a partially completed
32  * rewrite. Applications can use this information to inform users of the
33  * progress and the expected completion time.
34  */
36  std::uint64_t total_bytes_rewritten;
37  std::uint64_t object_size;
38  bool done;
39 };
40 
41 /**
42  * Complete long running object rewrite operations.
43  *
44  * The `Client::RewriteObject()` operation allows applications to copy objects
45  * across location boundaries, and to rewrite objects with different encryption
46  * keys. In some circumstances it may take multiple calls to the service to
47  * complete a rewrite, this class encapsulates the state of a partial copy.
48  */
50  public:
51  ObjectRewriter(std::shared_ptr<internal::RawClient> client,
52  internal::RewriteObjectRequest request);
53 
54  /**
55  * Perform one iteration in the rewrite.
56  *
57  * @return The progress after the iteration. If the rewrite has completed the
58  * application can use `Result()` to examine the metadata for the newly
59  * created object.
60  */
61  StatusOr<RewriteProgress> Iterate();
62 
63  /// The current progress on the rewrite operation.
64  StatusOr<RewriteProgress> CurrentProgress() const {
65  if (!last_error_.ok()) {
66  return last_error_;
67  }
68  return progress_;
69  }
70 
71  /**
72  * Iterate until the operation completes using a callback to report progress.
73  *
74  * @note This operation blocks until the copy is finished. For very large
75  * objects that could take substantial time. Applications may need to persist
76  * the rewrite operation. Some applications may want to wrap this call with
77  * `std::async`, and run the copy on a separate thread.
78  *
79  * @return the object metadata once the copy completes.
80  */
81  StatusOr<ObjectMetadata> Result() {
82  return ResultWithProgressCallback([](StatusOr<RewriteProgress> const&) {});
83  }
84 
85  /**
86  * Iterate until the operation completes using a callback to report progress.
87  *
88  * @note This operation blocks until the copy is finished. For very large
89  * objects that could take substantial time. Applications may need to persist
90  * the rewrite operation. Some applications may want to wrap this call with
91  * `std::async`, and run the copy on a separate thread.
92  *
93  * @param cb the callback object.
94  *
95  * @tparam Functor the type of the callback object. It must satisfy:
96  * `std:is_invocable<Functor, StatusOr<RewriteProgress>>:: value == true`.
97  *
98  * @return the object metadata once the copy completes.
99  */
100  template <
101  typename Functor,
102  typename std::enable_if<google::cloud::internal::is_invocable<
103  Functor, StatusOr<RewriteProgress>>::value,
104  int>::type = 0>
106  while (!progress_.done) {
107  cb(Iterate());
108  }
109  if (!last_error_.ok()) {
110  return last_error_;
111  }
112  return result_;
113  }
114 
115  /**
116  * The current rewrite token.
117  *
118  * Applications can save the token of partially completed rewrites, and
119  * restart those operations using `Client::CopyObjectRestart`, even if the
120  * application has terminated. It is up to the application to preserve
121  * all the other information for the request, including source and destination
122  * buckets, encryption keys, and any preconditions affecting the request.
123  *
124  * @note For rewrites that have not started the token is an empty string.
125  * For rewrites that have completed the token is also an empty string. The
126  * application should preserve other information (such as the
127  * `RewriteProgress`) to avoid repeating a rewrite.
128  */
129  std::string const& token() const { return request_.rewrite_token(); }
130 
131  private:
132  std::shared_ptr<internal::RawClient> client_;
133  internal::RewriteObjectRequest request_;
134  RewriteProgress progress_;
135  ObjectMetadata result_;
136  Status last_error_;
137 };
139 } // namespace storage
140 } // namespace cloud
141 } // namespace google
142 
143 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_REWRITER_H