diff --git a/reference/generator/generator.md b/reference/generator/generator.md index 2479b08d96..30840a4c89 100644 --- a/reference/generator/generator.md +++ b/reference/generator/generator.md @@ -32,6 +32,11 @@ namespace std { - `reference` == [`conditional_t`](/reference/type_traits/conditional.md)`<`[`is_void_v`](/reference/type_traits/is_void.md)`, Ref&&, Ref>` - [`iterator`](generator/iterator.md) : ジェネレータが返すイテレータ型。 +`generator`クラスの動作説明のため、下記の説明専用メンバを用いる。 + +- [`coroutine_handle`](/reference/coroutine/coroutine_handle.md)`<`[`promise_type`](generator/promise_type.md)`>` : コルーチンハンドル(`coroutine_`) +- [`unique_ptr`](/reference/memory/unique_ptr.md)`<`[`stack`](/reference/stack/stack.md)`<`[`coroutine_handle<>`](/reference/coroutine/coroutine_handle.md)`>>`: アクティブスタック(`active_`) + ## 適格要件 - テンプレートパラメータ`Allocator`が`void`ではない場合、[`allocator_traits`](/reference/memory/allocator_traits.md)`::pointer`はポインタ型であること。 diff --git a/reference/generator/generator/promise_type.md b/reference/generator/generator/promise_type.md index a5ac475d5c..7804d589c5 100644 --- a/reference/generator/generator/promise_type.md +++ b/reference/generator/generator/promise_type.md @@ -18,6 +18,11 @@ namespace std { ## 概要 ジェネレータコルーチン動作を制御する[Promise型](/lang/cpp20/coroutines.md)。 +`generator::promise_type`クラスの動作説明のため、以下の説明専用メンバを用いる。 + +- [`add_pointer_t`](/reference/type_traits/add_pointer.md)`<`[`yielded`](../../generator.md)`>`型 : `value_` +- [`exception_ptr`](/reference/exception/exception_ptr.md)型 : `except_` + ## メンバ関数 ### コルーチン @@ -31,8 +36,8 @@ namespace std { | [`await_transform`](promise_type/await_transform.md) | co_await式動作の制御 | C++23 | | [`return_void`](promise_type/return_void.md) | コルーチンreturn動作の制御 | C++23 | | [`unhandled_exception`](promise_type/unhandled_exception.md) | 未処理例外の制御 | C++23 | -| `operator new` | カスタムnew演算子 | C++23 | -| `operator delete` | カスタムdelete演算子 | C++23 | +| [`operator new`](promise_type/op_new.md) | new演算子オーバーロード | C++23 | +| [`operator delete`](promise_type/op_delete.md) | delete演算子オーバーロード | C++23 | ## バージョン diff --git a/reference/generator/generator/promise_type/final_suspend.md b/reference/generator/generator/promise_type/final_suspend.md index 59110efc06..0451a8d813 100644 --- a/reference/generator/generator/promise_type/final_suspend.md +++ b/reference/generator/generator/promise_type/final_suspend.md @@ -14,11 +14,14 @@ auto final_suspend() noexcept; ## 事前条件 -(執筆中) +Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタックのトップにあること。 +この関数はコルーチン実行が最終サスペンドポイントに到達したときに呼び出される。 ## 戻り値 -(執筆中) +下記動作を行うメンバ関数をもつ、未規定の型のAwaitableオブジェクト。 + +コルーチンの中断(suspend)時に、ジェネレータ`x`のアクティブスタックのトップからコルーチンハンドルをpopし、アクティブスタックが空でなければトップ要素が指すコルーチンを再開(resume)する。アクティブスタックが空の場合は、現在の[コルーチンの呼び出し元もしくは再開元(resumer)](/lang/cpp20/coroutines.md)へ制御フローを戻す。 ## 例外 diff --git a/reference/generator/generator/promise_type/get_return_object.md b/reference/generator/generator/promise_type/get_return_object.md index 77d606c3fd..e6ddea443b 100644 --- a/reference/generator/generator/promise_type/get_return_object.md +++ b/reference/generator/generator/promise_type/get_return_object.md @@ -12,6 +12,7 @@ generator get_return_object() noexcept; ## 概要 ジェネレータ[コルーチン](/lang/cpp20/coroutines.md)の戻り値オブジェクトを生成する。 +戻り値ジェネレータの[アクティブスタック](../../generator.md)を、空(empty)で初期化する。 ## 戻り値 diff --git a/reference/generator/generator/promise_type/op_delete.md b/reference/generator/generator/promise_type/op_delete.md new file mode 100644 index 0000000000..b3a29b1242 --- /dev/null +++ b/reference/generator/generator/promise_type/op_delete.md @@ -0,0 +1,36 @@ +# operator delete +* generator[meta header] +* function[meta id-type] +* std[meta namespace] +* generator::promise_type[meta class] +* cpp23[meta cpp] + +```cpp +void operator delete(void* pointer, size_t size) noexcept; +``` + +## 概要 +[`generator::promise_type`クラス](../promise_type.md)のdelete演算子オーバーロード。 + + +## 事前条件 +`pointer`は`size`と同一サイズで[`operator new`](op_new.md)により確保されたストレージを指すポインタ値。 + + +## 効果 +[確保時と同じアロケータ](op_new.md)を用いて、`pointer`が指すストレージを解放する。 + + +## バージョン +### 言語 +- C++23 + +### 処理系 +- [Clang](/implementation.md#clang): ?? +- [GCC](/implementation.md#gcc): ?? +- [ICC](/implementation.md#icc): ?? +- [Visual C++](/implementation.md#visual_cpp): ?? + + +## 関連項目 +- [`operator new`](op_new.md) diff --git a/reference/generator/generator/promise_type/op_new.md b/reference/generator/generator/promise_type/op_new.md new file mode 100644 index 0000000000..e291d024ae --- /dev/null +++ b/reference/generator/generator/promise_type/op_new.md @@ -0,0 +1,64 @@ +# operator new +* generator[meta header] +* function template[meta id-type] +* std[meta namespace] +* generator::promise_type[meta class] +* cpp23[meta cpp] + +```cpp +void* operator new(size_t size) + requires same_as || default_initializable; // (1) + +template + requires same_as || convertible_to +void* operator new(size_t size, allocator_arg_t, const Alloc& alloc, const Args&...); // (2) + +template + requires same_as || convertible_to +void* operator new(size_t size, const This&, allocator_arg_t, const Alloc& alloc, const Args&...); +``` +* std::same_as[link /reference/concepts/same_as.md] +* default_initializable[link /reference/concepts/default_initializable.md] +* std::convertible_to[link /reference/concepts/convertible_to.md] +* allocator_arg_t[link /reference/memory/allocator_arg_t.md] + + +## 概要 +[`generator::promise_type`クラス](../promise_type.md)のnew演算子オーバーロード。 + +ここで動作説明用の型をいくつか導入する。`A`型を下記の通りとする。 + +- [`generator`](../../generator.md)クラステンプレートのテンプレートパラメータ`Allocator`が`void`でなければ、`Allocator`。 +- テンプレートパラメータ`Alloc`を持つオーバーロードでは、`Alloc`。 +- そうでなければ[`allocator`](/reference/memory/allocator.md)。 + +`U`型をサイズおよびアライメントが[`__STDCPP_DEFAULT_NEW_ALIGNMENT__`](/lang/cpp17/predefined_macros.md)に等しい未規定の型としたとき、`B`型を[`allocator_traits`](/reference/memory/allocator_traits.md)`::template rebind_alloc`とする。 + + +## 適格要件 +[`allocator_traits`](/reference/memory/allocator_traits.md)`::pointer`はポインタ型。 + + +## 効果 +`B`型のアロケータ`b`を、オーバーロード(1)では`A()`により、オーバーロード(2)(3)では`A(alloc)`により初期化する。 + +アロケータ`b`を用いて、サイズ`size`の[コルーチン・ステー](/lang/cpp20/coroutines.md)トと、後ほど[`operator delete`](op_delete.md)による`b`を用いたメモリブロック解放で必要とされる追加状態を合わせたストレージに必要となる、`U`型の最小配列ストレージを確保する。 + + +## 戻り値 +確保されたストレージへのポインタ。 + + +## バージョン +### 言語 +- C++23 + +### 処理系 +- [Clang](/implementation.md#clang): ?? +- [GCC](/implementation.md#gcc): ?? +- [ICC](/implementation.md#icc): ?? +- [Visual C++](/implementation.md#visual_cpp): ?? + + +## 関連項目 +- [`operator delete`](op_delete.md) diff --git a/reference/generator/generator/promise_type/unhandled_exception.md b/reference/generator/generator/promise_type/unhandled_exception.md index fce2ef35c4..7b67e4121d 100644 --- a/reference/generator/generator/promise_type/unhandled_exception.md +++ b/reference/generator/generator/promise_type/unhandled_exception.md @@ -14,11 +14,13 @@ void unhandled_exception(); ## 事前条件 -(執筆中) +Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタックのトップにあること。 ## 効果 -(執筆中) +Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)がジェネレータ`x`のアクティブスタックの単独要素であれば、式`throw;`に等しい。 + +そうでなければ、[説明専用メンバ`except_`](../promise_type.md)に[`current_exception()`](/reference/exception/current_exception.md)を代入する。 ## バージョン @@ -30,3 +32,7 @@ void unhandled_exception(); - [GCC](/implementation.md#gcc): ?? - [ICC](/implementation.md#icc): ?? - [Visual C++](/implementation.md#visual_cpp): ?? + + +## 関連項目 +- [`yield_value`](yield_value.md) diff --git a/reference/generator/generator/promise_type/yield_value.md b/reference/generator/generator/promise_type/yield_value.md index 70f9a3fa75..c1d4e2ae43 100644 --- a/reference/generator/generator/promise_type/yield_value.md +++ b/reference/generator/generator/promise_type/yield_value.md @@ -1,6 +1,6 @@ -# unhandled_exception +# yield_value * generator[meta header] -* function[meta id-type] +* function template[meta id-type] * std[meta namespace] * generator::promise_type[meta class] * cpp23[meta cpp] @@ -39,11 +39,58 @@ auto yield_value(ranges::elements_of r) noexcept; // (4) ## 事前条件 -(執筆中) +- (2) : Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタックのトップにあること。 +- (3) : Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタックのトップにあること。ジェネレータ`g.range`に対応するコルーチンが、初期サスペンドポイントにて中断されていること。 ## 効果 -(執筆中) +(1) : 以下と等価 +```cpp +value_ = addressof(val) +``` +* value_[link ../promise_type.md] +* addressof[link /reference/memory/addressof.md] + +(4) : 以下と等価 +```cpp +auto nested = [](allocator_arg_t, Alloc, ranges::iterator_t i, + ranges::sentinel_t s) + -> generator, Alloc> { + for (; i != s; ++i) { + co_yield static_cast(*i); + } + }; +return yield_value(ranges::elements_of(nested( + allocator_arg, r.allocator, ranges::begin(r.range), ranges::end(r.range)))); +``` +* co_yield[link /lang/cpp20/coroutines.md] +* generator[link ../../generator.md] +* yielded[link ../../generator.md] +* allocator_arg_t[link /reference/memory/allocator_arg_t.md] +* allocator_arg[link /reference/memory/allocator_arg_t.md] +* ranges::iterator_t[link /reference/ranges/iterator_t.md] +* ranges::sentinel_t[link /reference/ranges/sentinel_t.md] +* ranges::range_value_t[link /reference/ranges/range_value_t.md] +* ranges::elements_of[link /reference/ranges/elements_of.md] +* r.range[link /reference/ranges/elements_of.md] +* r.allocator[link /reference/ranges/elements_of.md] +* ranges::begin[link /reference/ranges/begin.md] +* ranges::end[link /reference/ranges/end.md] + + +## 戻り値 +- (1) : [`suspend_always{}`](/reference/coroutine/suspend_always.md) +- (2) : `lval`を用いて直接非リスト初期化(direct-non-list-initialized)された[`remove_cvref_t`](/reference/type_traits/remove_cvref.md)`<`[`yielded`](../../generator.md)`>`型オブジェクトを保持し、[説明専用メンバ`value_`](../promise_type.md)が保持されたオブジェクトを指してコルーチンを中断(suspend)するメンバ関数をもつ、未規定の型の[Awaitableオブジェクト](/lang/cpp20/coroutines.md)。 +- (3) : ジェネレータ`g.range`の所有権を受け取り、メンバ関数`await_ready`は`false`を返し、メンバ関数`await_suspend`は`x`のアクティブスタックに`g.range`に対応する[コルーチンハンドル](/reference/coroutine/coroutine_handle.md)をpushしてから`g.range`を再開(resume)し、メンバ関数`await_resume`は[説明専用メンバ`except_`](../promise_type.md)が例外を保持している場合に[`rethrow_exception`](/reference/exception/rethrow_exception.md)`(except_)`を行う、未規定の型の[Awaitableオブジェクト](/lang/cpp20/coroutines.md)。 + + +## 例外 +- (1) : 投げない。 +- (2) : 格納されるオブジェクトの初期化によって送出された例外。 + + +## 備考 +この関数を呼び出す`co_yield`式は`void`型となる。 ## バージョン @@ -55,3 +102,7 @@ auto yield_value(ranges::elements_of r) noexcept; // (4) - [GCC](/implementation.md#gcc): ?? - [ICC](/implementation.md#icc): ?? - [Visual C++](/implementation.md#visual_cpp): ?? + + +## 関連項目 +- [`unhandled_exception`](unhandled_exception.md)