Google Cloud C++ Client  1.32.1
C++ Client Library for Google Cloud Platform
future_generic.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_FUTURE_GENERIC_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_FUTURE_GENERIC_H
17 /**
18  * @file
19  *
20  * Fully specialize `future<void>` and `promise<R>` for void.
21  */
22 
23 #include "google/cloud/internal/future_base.h"
24 #include "google/cloud/internal/future_fwd.h"
25 #include "google/cloud/internal/future_impl.h"
26 #include "google/cloud/internal/future_then_meta.h"
27 #include "google/cloud/version.h"
28 
29 namespace google {
30 namespace cloud {
31 inline namespace GOOGLE_CLOUD_CPP_NS {
32 /**
33  * Implement ISO/IEC TS 19571:2016 `future<T>`.
34  */
35 template <typename T>
36 class future final : private internal::future_base<T> {
37  public:
38  using shared_state_type =
39  typename internal::future_base<T>::shared_state_type;
40 
41  // workaround Apple Clang-7xx series bug, if we use `= default` here, the
42  // compiler believes there is no default constructor defined. :shrug:
43  future() noexcept {} // NOLINT(modernize-use-equals-default)
44 
45  /**
46  * Creates a new future that unwraps @p rhs.
47  *
48  * This constructor creates a new shared state that becomes satisfied when
49  * both `rhs` and `rhs.get()` become satisfied. If `rhs` is satisfied, but
50  * `rhs.get()` returns an invalid future then the newly created future becomes
51  * satisfied with a `std::future_error` exception, and the exception error
52  * code is `std::future_errc::broken_promise`.
53  *
54  * @note The technical specification requires this to be a `noexcept`
55  * constructor I (coryan) believe this is a defect in the technical
56  * specification, as this *creates* a new shared state: shared states are
57  * dynamically allocated, and the allocator (which might be the default
58  * `operator new`) may raise.
59  */
60  // NOLINTNEXTLINE(google-explicit-constructor)
61  future(future<future<T>>&& rhs) noexcept(false);
62 
63  /**
64  * Waits until the shared state becomes ready, then retrieves the value stored
65  * in the shared state.
66  *
67  * @note This operation invalidates the future, subsequent calls will fail,
68  * the application should capture the returned value because it would.
69  *
70  * @throws any exceptions stored in the shared state.
71  * @throws std::future_error with std::no_state if the future does not have
72  * a shared state.
73  */
74  T get() {
75  this->check_valid();
76  std::shared_ptr<shared_state_type> tmp;
77  tmp.swap(this->shared_state_);
78  return tmp->get();
79  }
80 
81  using internal::future_base<T>::cancel;
82  using internal::future_base<T>::is_ready;
83  using internal::future_base<T>::valid;
84  using internal::future_base<T>::wait;
85  using internal::future_base<T>::wait_for;
86  using internal::future_base<T>::wait_until;
87 
88  /**
89  * Attach a continuation to the future.
90  *
91  * Attach a callable @a func to be invoked when the future is
92  * ready. The return type is a future wrapping the return type of
93  * @a func.
94  *
95  * @return `future<T>` where T is `std::result_of_t<F, R>` (basically).
96  * If T matches `future<U>` then it returns `future<U>`. The returned
97  * future will contain the result of @a func.
98  * @param func a Callable to be invoked when the future is ready.
99  * The function might be called immediately, e.g., if the future is
100  * ready.
101  *
102  * Side effects: `valid() == false` if the operation is successful.
103  */
104  template <typename F>
105  typename internal::then_helper<F, T>::future_t then(F&& func) {
106  this->check_valid();
107  using requires_unwrap_t =
108  typename internal::then_helper<F, T>::requires_unwrap_t;
109  return then_impl(std::forward<F>(func), requires_unwrap_t{});
110  }
111 
112  explicit future(std::shared_ptr<shared_state_type> state)
113  : internal::future_base<T>(std::move(state)) {}
114 
115  private:
116  /// Implement `then()` if the result does not require unwrapping.
117  template <typename F>
118  typename internal::then_helper<F, T>::future_t then_impl(F&& functor,
119  std::false_type);
120 
121  /// Implement `then()` if the result requires unwrapping.
122  template <typename F>
123  typename internal::then_helper<F, T>::future_t then_impl(F&& functor,
124  std::true_type);
125 
126  template <typename U>
127  friend class future;
128  friend class future<void>;
129 };
130 
131 /**
132  * Implement `promise<T>` as defined in ISO/IEC TS 19571:2016.
133  */
134 template <typename T>
135 class promise final : private internal::promise_base<T> {
136  public:
137  /// Creates a promise with an unsatisfied shared state.
138  promise() : internal::promise_base<T>([] {}) {}
139 
140  /// Creates a promise with an unsatisfied shared state.
141  explicit promise(std::function<void()> cancellation_callback)
142  : internal::promise_base<T>(std::move(cancellation_callback)) {}
143 
144  /// Creates a promise *without* a shared state.
145  explicit promise(null_promise_t x)
146  : internal::promise_base<T>(std::move(x)) {}
147 
148  /// Constructs a new promise and transfer any shared state from @p rhs.
149  // NOLINTNEXTLINE(performance-noexcept-move-constructor)
150  promise(promise&&) = default;
151 
152  /// Abandons the shared state in `*this`, if any, and transfers the shared
153  /// state from @p rhs.
154  promise& operator=(promise&& rhs) noexcept {
155  promise tmp(std::move(rhs));
156  this->swap(tmp);
157  return *this;
158  }
159 
160  /**
161  * Abandons any shared state.
162  *
163  * If the shared state was not already satisfied it becomes satisfied with
164  * a `std::future_error` exception. The error code in this exception is
165  * `std::future_errc::broken_promise`.
166  */
167  ~promise() = default;
168 
169  promise(promise const&) = delete;
170  promise& operator=(promise const&) = delete;
171 
172  /// Swaps the shared state in `*this` with @p rhs.
173  void swap(promise& other) noexcept {
174  std::swap(this->shared_state_, other.shared_state_);
175  }
176 
177  /**
178  * Creates the `future<T>` using the same shared state as `*this`.
179  */
181  internal::future_shared_state<T>::mark_retrieved(this->shared_state_);
182  return future<T>(this->shared_state_);
183  }
184 
185  /**
186  * Satisfies the shared state.
187  *
188  * @throws std::future_error with std::future_errc::promise_already_satisfied
189  * if the shared state is already satisfied.
190  * @throws std::future_error with std::no_state if the promise does not have
191  * a shared state.
192  */
193  void set_value(T value) {
194  if (!this->shared_state_) {
195  internal::ThrowFutureError(std::future_errc::no_state, __func__);
196  }
197  this->shared_state_->set_value(std::move(value));
198  }
199 
200  using internal::promise_base<T>::set_exception;
201 };
202 
203 /// Create a future<void> that is immediately ready.
204 template <typename T>
205 inline future<typename internal::make_ready_return<T>::type> make_ready_future(
206  T&& t) {
207  using V = typename internal::make_ready_return<T>::type;
208  // TODO(#1410) - Implement specializations of future<R&> and promise<R&>.
209  static_assert(!std::is_reference<V>::value, "future<R&> is not implemented");
210  promise<V> p;
211  p.set_value(std::forward<T>(t));
212  return p.get_future();
213 }
214 
215 } // namespace GOOGLE_CLOUD_CPP_NS
216 } // namespace cloud
217 } // namespace google
218 
219 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_FUTURE_GENERIC_H