[coro.generator.promise] - C++20 → C++23

Files changed (1) hide show

tmp/tmpuajzugdd/{from.md → to.md} +209 -0

tmp/tmpuajzugdd/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,209 @@

+### Class `generator::promise_type` <a id="coro.generator.promise">[[coro.generator.promise]]</a>
+``` cpp
+namespace std {
+  template<class Ref, class V, class Allocator>
+  class generator<Ref, V, Allocator>::promise_type {
+  public:
+    generator get_return_object() noexcept;
+    suspend_always initial_suspend() const noexcept { return {}; }
+    auto final_suspend() noexcept;
+    suspend_always yield_value(yielded val) noexcept;
+    auto yield_value(const remove_reference_t<yielded>& lval)
+      requires is_rvalue_reference_v<yielded> &&
+        constructible_from<remove_cvref_t<yielded>, const remove_reference_t<yielded>&>;
+    template<class R2, class V2, class Alloc2, class Unused>
+      requires same_as<typename generator<R2, V2, Alloc2>::yielded, yielded>
+        auto yield_value(ranges::elements_of<generator<R2, V2, Alloc2>&&, Unused> g) noexcept;
+    template<ranges::input_range R, class Alloc>
+      requires convertible_to<ranges::range_reference_t<R>, yielded>
+        auto yield_value(ranges::elements_of<R, Alloc> r) noexcept;
+    void await_transform() = delete;
+    void return_void() const noexcept {}
+    void unhandled_exception();
+    void* operator new(size_t size)
+      requires same_as<Allocator, void> || default_initializable<Allocator>;
+    template<class Alloc, class... Args>
+      requires same_as<Allocator, void> || convertible_to<const Alloc&, Allocator>
+        void* operator new(size_t size, allocator_arg_t, const Alloc& alloc, const Args&...);
+    template<class This, class Alloc, class... Args>
+      requires same_as<Allocator, void> || convertible_to<const Alloc&, Allocator>
+        void* operator new(size_t size, const This&, allocator_arg_t, const Alloc& alloc,
+                           const Args&...);
+    void operator delete(void* pointer, size_t size) noexcept;
+  private:
+    add_pointer_t<yielded> value_ = nullptr;    // exposition only
+    exception_ptr except_;                      // exposition only
+  };
+}
+```
+``` cpp
+generator get_return_object() noexcept;
+```
+*Returns:* A `generator` object whose member *coroutine\_* is
+`coroutine_handle<promise_type>::from_promise(*this)`, and whose member
+*active\_* points to an empty stack.
+``` cpp
+auto final_suspend() noexcept;
+```
+*Preconditions:* A handle referring to the coroutine whose promise
+object is `*this` is at the top of `*`*`active_`* of some `generator`
+object `x`. This function is called by that coroutine upon reaching its
+final suspend point [[dcl.fct.def.coroutine]].
+*Returns:* An awaitable object of unspecified type [[expr.await]] whose
+member functions arrange for the calling coroutine to be suspended, pop
+the coroutine handle from the top of `*x.`*`active_`*, and resume
+execution of the coroutine referred to by `x.`*`active_`*`->top()` if
+`*x.`*`active_`* is not empty. If it is empty, control flow returns to
+the current coroutine caller or resumer [[dcl.fct.def.coroutine]].
+``` cpp
+suspend_always yield_value(yielded val) noexcept;
+```
+*Effects:* Equivalent to *`value_`*` = addressof(val)`.
+*Returns:* `{}`.
+``` cpp
+auto yield_value(const remove_reference_t<yielded>& lval)
+  requires is_rvalue_reference_v<yielded> &&
+    constructible_from<remove_cvref_t<yielded>, const remove_reference_t<yielded>&>;
+```
+*Preconditions:* A handle referring to the coroutine whose promise
+object is `*this` is at the top of `*`*`active_`* of some `generator`
+object.
+*Returns:* An awaitable object of an unspecified type [[expr.await]]
+that stores an object of type `remove_cvref_t<yielded>`
+direct-non-list-initialized with `lval`, whose member functions arrange
+for *value\_* to point to that stored object and then suspend the
+coroutine.
+*Throws:* Any exception thrown by the initialization of the stored
+object.
+*Remarks:* A *yield-expression* that calls this function has type `void`
+[[expr.yield]].
+``` cpp
+template<class R2, class V2, class Alloc2, class Unused>
+  requires same_as<typename generator<R2, V2, Alloc2>::yielded, yielded>
+  auto yield_value(ranges::elements_of<generator<R2, V2, Alloc2>&&, Unused> g) noexcept;
+```
+*Preconditions:* A handle referring to the coroutine whose promise
+object is `*this` is at the top of `*`*`active_`* of some `generator`
+object `x`. The coroutine referred to by `g.range.`*`coroutine_`* is
+suspended at its initial suspend point.
+*Returns:* An awaitable object of an unspecified type [[expr.await]]
+into which `g.range` is moved, whose member `await_ready` returns
+`false`, whose member `await_suspend` pushes
+`g.range.`\textit{coroutine\_} into `*x.`*`active_`* and resumes
+execution of the coroutine referred to by `g.range.`*`coroutine_`*, and
+whose member `await_resume` evaluates `rethrow_exception(`*`except_`*`)`
+if `bool(`*`except_`*`)` is `true`. If `bool(`*`except_`*`)` is `false`,
+the `await_resume` member has no effects.
+*Remarks:* A *yield-expression* that calls this function has type `void`
+[[expr.yield]].
+``` cpp
+template<ranges::input_range R, class Alloc>
+  requires convertible_to<ranges::range_reference_t<R>, yielded>
+  auto yield_value(ranges::elements_of<R, Alloc> r) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+auto nested = [](allocator_arg_t, Alloc, ranges::iterator_t<R> i, ranges::sentinel_t<R> s)
+  -> generator<yielded, ranges::range_value_t<R>, Alloc> {
+    for (; i != s; ++i) {
+      co_yield static_cast<yielded>(*i);
+    }
+  };
+return yield_value(ranges::elements_of(nested(
+  allocator_arg, r.allocator, ranges::begin(r.range), ranges::end(r.range))));
+```
+[*Note 1*: A *yield-expression* that calls this function has type
+`void` [[expr.yield]]. — *end note*]
+``` cpp
+void unhandled_exception();
+```
+*Preconditions:* A handle referring to the coroutine whose promise
+object is `*this` is at the top of `*`*`active_`* of some `generator`
+object `x`.
+*Effects:* If the handle referring to the coroutine whose promise object
+is `*this` is the sole element of `*x.`*`active_`*, equivalent to
+`throw`, otherwise, assigns `current_exception()` to *except\_*.
+``` cpp
+void* operator new(size_t size)
+  requires same_as<Allocator, void> || default_initializable<Allocator>;
+template<class Alloc, class... Args>
+  requires same_as<Allocator, void> || convertible_to<const Alloc&, Allocator>
+  void* operator new(size_t size, allocator_arg_t, const Alloc& alloc, const Args&...);
+template<class This, class Alloc, class... Args>
+  requires same_as<Allocator, void> || convertible_to<const Alloc&, Allocator>
+  void* operator new(size_t size, const This&, allocator_arg_t, const Alloc& alloc,
+                     const Args&...);
+```
+Let `A` be
+- `Allocator`, if it is not `void`,
+- `Alloc` for the overloads with a template parameter `Alloc`, or
+- `allocator<void>` otherwise.
+Let `B` be `allocator_traits<A>::template rebind_alloc<U>` where `U` is
+an unspecified type whose size and alignment are both
+\_\_STDCPP_DEFAULT_NEW_ALIGNMENT\_\_.
+*Mandates:* `allocator_traits<B>::pointer` is a pointer type.
+*Effects:* Initializes an allocator `b` of type `B` with `A(alloc)`, for
+the overloads with a function parameter `alloc`, and with `A()`
+otherwise. Uses `b` to allocate storage for the smallest array of `U`
+sufficient to provide storage for a coroutine state of size `size`, and
+unspecified additional state necessary to ensure that `operator delete`
+can later deallocate this memory block with an allocator equal to `b`.
+*Returns:* A pointer to the allocated storage.
+``` cpp
+void operator delete(void* pointer, size_t size) noexcept;
+```
+*Preconditions:* `pointer` was returned from an invocation of one of the
+above overloads of `operator new` with a `size` argument equal to
+`size`.
+*Effects:* Deallocates the storage pointed to by `pointer` using an
+allocator equivalent to that used to allocate it.

Diff to HTML by rtfpessoa