Google Cloud C++ Client  1.32.1
C++ Client Library for Google Cloud Platform
future_void.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_VOID_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_FUTURE_VOID_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 for void.
34  */
35 template <>
36 class future<void> final : private internal::future_base<void> {
37  public:
38  using shared_state_type =
39  typename internal::future_base<void>::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<void>>&& 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  * @throws any exceptions stored in the shared state.
68  * @throws std::future_error with std::no_state if the future does not have
69  * a shared state.
70  */
71  void get() {
72  check_valid();
73  std::shared_ptr<shared_state_type> tmp;
74  tmp.swap(shared_state_);
75  return tmp->get();
76  }
77 
78  using future_base::cancel;
79  using future_base::is_ready;
80  using future_base::valid;
81  using future_base::wait;
82  using future_base::wait_for;
83  using future_base::wait_until;
84 
85  /**
86  * Attach a continuation to the future.
87  *
88  * Attach a callable @a func to be invoked when the future is
89  * ready. The return type is a future wrapping the return type of
90  * @a func.
91  *
92  * @return `future<T>` where T is `std::result_of_t<F, R>` (basically).
93  * If T matches `future<U>` then it returns `future<U>`. The returned
94  * future will contain the result of @a func.
95  * @param func a Callable to be invoked when the future is ready.
96  * The function might be called immediately, e.g., if the future is
97  * ready.
98  *
99  * Side effects: `valid() == false` if the operation is successful.
100  */
101  template <typename F>
102  typename internal::then_helper<F, void>::future_t then(F&& func) {
103  check_valid();
104  using requires_unwrap_t =
105  typename internal::then_helper<F, void>::requires_unwrap_t;
106  return then_impl(std::forward<F>(func), requires_unwrap_t{});
107  }
108 
109  explicit future(std::shared_ptr<shared_state_type> state)
110  : future_base<void>(std::move(state)) {}
111 
112  private:
113  /// Implement `then()` if the result does not require unwrapping.
114  template <typename F>
115  typename internal::then_helper<F, void>::future_t then_impl(F&& functor,
116  std::false_type);
117 
118  /// Implement `then()` if the result requires unwrapping.
119  template <typename F>
120  typename internal::then_helper<F, void>::future_t then_impl(F&& functor,
121  std::true_type);
122 
123  template <typename U>
124  friend class future;
125 };
126 
127 /**
128  * Specialize promise as defined in ISO/IEC TS 19571:2016 for void.
129  */
130 template <>
131 class promise<void> final : private internal::promise_base<void> {
132  public:
133  /// Creates a promise with an unsatisfied shared state.
134  promise() : promise_base([] {}) {}
135 
136  /// Creates a promise with an unsatisfied shared state.
137  explicit promise(std::function<void()> cancellation_callback)
138  : promise_base(std::move(cancellation_callback)) {}
139 
140  /// Creates a promise *without* a shared state.
141  explicit promise(null_promise_t x) : promise_base(std::move(x)) {}
142 
143  /// Constructs a new promise and transfer any shared state from @p rhs.
144  promise(promise&&) = default;
145 
146  /// Abandons the shared state in `*this`, if any, and transfers the shared
147  /// state from @p rhs.
148  promise& operator=(promise&& rhs) noexcept {
149  promise tmp(std::move(rhs));
150  tmp.swap(*this);
151  return *this;
152  }
153 
154  /**
155  * Abandons any shared state.
156  *
157  * If the shared state was not already satisfied it becomes satisfied with
158  * a `std::future_error` exception. The error code in this exception is
159  * `std::future_errc::broken_promise`.
160  */
161  ~promise() = default;
162 
163  promise(promise const&) = delete;
164  promise& operator=(promise const&) = delete;
165 
166  /// Swaps the shared state in `*this` with @p rhs.
167  void swap(promise& other) noexcept {
168  std::swap(shared_state_, other.shared_state_);
169  }
170 
171  /**
172  * Creates the `future<void>` using the same shared state as `*this`.
173  */
174  future<void> get_future() {
175  shared_state_type::mark_retrieved(shared_state_);
176  return future<void>(shared_state_);
177  }
178 
179  /**
180  * Satisfies the shared state.
181  *
182  * @throws std::future_error with std::future_errc::promise_already_satisfied
183  * if the shared state is already satisfied.
184  * @throws std::future_error with std::no_state if the promise does not have
185  * a shared state.
186  */
187  void set_value() {
188  if (!shared_state_) {
189  internal::ThrowFutureError(std::future_errc::no_state, __func__);
190  }
191  shared_state_->set_value();
192  }
193 
194  using promise_base<void>::set_exception;
195 };
196 
197 /// Create a future<void> that is immediately ready.
198 inline future<void> make_ready_future() {
199  promise<void> p;
200  p.set_value();
201  return p.get_future();
202 }
203 
204 } // namespace GOOGLE_CLOUD_CPP_NS
205 } // namespace cloud
206 } // namespace google
207 
208 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_FUTURE_VOID_H