polymorphic_allocator : P0339R6対応 #642

Author: onihusube

reference/memory_resource/memory_resource/allocate.md

@@ -15,15 +15,16 @@ void* allocate(size_t bytes, size_t alignment = alignof(max_align_t)); // (1) C+
 * max_align_t[link /reference/cstddef/max_align_t.md]
 
 ## 概要
-メモリを確保する。
+
+指定されたバイト数とアライメントでメモリを確保する。
 
 ## 事前条件
 呼び出す`do_allocate`の要件として  
 `alignment`は2の累乗であること。
 
 ## 引数
-- `bytes` -- 確保したい領域のサイズ
-- `alignment` -- 確保領域のアライメント要求
+- `bytes` -- 確保したい領域のサイズ（バイト数）
+- `alignment` -- 確保領域へのアライメント要求
 
 ## 効果
 `return this->do_allocate(bytes, alignment);` と等価。  

reference/memory_resource/memory_resource/deallocate.md

@@ -13,7 +13,7 @@ void deallocate(void* p, std::size_t bytes, std::size_t alignment = alignof(std:
 ## 概要
 [`allocate`](allocate.md)によって確保されたメモリを解放する。
 
-## 要件
+## 事前条件
 呼び出す`do_deallocate`の要件として  
 `p`の指すサイズ`bytes`のメモリ領域は、`*this`もしくは等しい`memory_resource`オブジェクト（`this->is_equal(other) == true`となるような`other`）の[`allocate`](allocate.md)`(bytes, alignment)`によって事前に確保された領域であること。  
 かつ、そのメモリ領域は未解放であること。

reference/memory_resource/polymorphic_allocator.md

@@ -7,25 +7,54 @@
 ```cpp
 namespace std::pmr {
   template <class Tp>
-  class polymorphic_allocator;
+  class polymorphic_allocator;    //C++17
+
+  template <class Tp = byte>
+  class polymorphic_allocator;    //C++20
 }
 ```
+* byte[link /reference/cstddef/byte.md]
 
 ## 概要
 `polymorphic_allocator`は任意の[`memory_resource`](memory_resource.md)実装によりメモリ確保・解放戦略に関わる実際の処理を動的に切り替えることのできるアロケータである。この様な設計は一般にStrategyパターンというデザインパターンの一つとして知られている。 
 
 このクラスと[`memory_resource`](memory_resource.md)の利用により、同じ静的型`polymorphic_allocator<Tp>`で実行時に異なるメモリの確保・解放戦略をとるアロケータの利用が可能になる。
 
+C++20にてC++プログラミングにおいての基礎部品となる型（*vocabulary type*）となるように改修され、`polymorphic_allocator<>`の形で幅広く利用できるようになった。
+
 ## メンバ関数
 
+### 構築・破棄
+
 | 名前            | 説明           | 対応バージョン |
 |-----------------|----------------|----------------|
 | [`(constructor)`](polymorphic_allocator/op_constructor.md) | コンストラクタ | C++17 |
 | `operator=(const polymorphic_allocator& rhs) = delete;`     | コピー代入演算子（コピー禁止）     | C++17 |
-| [`allocate`](polymorphic_allocator/allocate.md) | メモリを確保する | C++17 |
-| [`deallocate`](polymorphic_allocator/deallocate.md) | メモリを解放する | C++17 |
+
+### メモリ確保・解放のみを行う関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|----------------|
+| [`allocate`](polymorphic_allocator/allocate.md) | `Tp`の指定した要素数分のメモリを確保する | C++17 |
+| [`deallocate`](polymorphic_allocator/deallocate.md) | `Tp`の指定した要素数分のメモリを解放する | C++17 |
+| [`allocate_bytes`](polymorphic_allocator/allocate_bytes.md) | 指定したバイト数のメモリを確保する | C++20 |
+| [`deallocate_bytes`](polymorphic_allocator/deallocate_bytes.md) | 指定したバイト数のメモリを解放する | C++20 |
+| [`allocate_object`](polymorphic_allocator/allocate_object.md) | 指定した型の指定した要素数分のメモリを確保する | C++20 |
+| [`deallocate_object`](polymorphic_allocator/deallocate_object.md) | 指定した型の指定した要素数分のメモリを解放する | C++20 |
+
+### オブジェクト構築・破棄を行う関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|----------------|
 | [`construct`](polymorphic_allocator/construct.md) | 指定された領域にオブジェクトを構築する | C++17 |
 | [`destroy`](polymorphic_allocator/destroy.md) | 指定された領域のオブジェクトを破棄する | C++17 |
+| [`new_object`](polymorphic_allocator/new_object.md) | メモリを確保し指定した型の構築（`new`式相当の処理）を行う | C++20 |
+| [`delete_object`](polymorphic_allocator/delete_object.md) | 指定した型の破棄とそのメモリ領域の解放（`delete`式相当の処理）を行う | C++20 |
+
+### その他関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|----------------|
 | [`select_on_container_copy_construction`](polymorphic_allocator/select_on_container_copy_construction.md) | コンテナのコピー構築時に新しい`polymorphic_allocator<Tp>`を取得する | C++17 |
 | [`resource`](polymorphic_allocator/resource.md) | 使用している`memory_resource`を取得する | C++17 |
 
@@ -61,4 +90,5 @@ namespace std::pmr {
 - [Polymorphic Allocator in C++17 - Qita](https://qiita.com/MitsutakaTakeda/items/48980faa9498c46b15b2)
 - [P0220R1 Adopt Library Fundamentals V1 TS Components for C++17 (R1)](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html)
 - [P0337r0 | Delete operator= for polymorphic_allocator](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0337r0.html)
-- [Working Draft, C++ Extensions for Library Fundamentals, Version 2](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4562.html#memory.resource.synop)
+- [Working Draft, C++ Extensions for Library Fundamentals, Version 2](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4562.html#memory.resource.synop)
+- [P0339R6 polymorphic_allocator<> as a vocabulary type](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0339r6.pdf)

reference/memory_resource/polymorphic_allocator/allocate_bytes.md

@@ -0,0 +1,115 @@
+# allocate_bytes
+* memory_resource[meta header]
+* function[meta id-type]
+* std::pmr[meta namespace]
+* polymorphic_allocator[meta class]
+* cpp17[meta cpp]
+
+```cpp
+void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
+```
+* max_align_t[link /reference/cstddef/max_align_t.md]
+
+## 概要
+
+指定されたバイト数とアライメントでメモリを確保する。
+
+## 事前条件
+
+`alignment`は2の累乗であること。
+
+## 引数
+
+- `nbytes` -- 確保したい領域のサイズ（バイト数）
+- `alignment` --  確保領域へのアライメント要求
+
+
+## 効果
+
+利用する[`memory_resource`](/reference/memory_resource/memory_resource.md)のポインタを`memory_rsrc`というメンバに保持しているとすると、以下と等価。
+
+```cpp
+return memory_­rsrc->allocate(nbytes, alignment);
+```
+* allocate[link /reference/memory_resource/memory_resource/allocate.md]
+
+## 戻り値
+
+確保した領域の先頭へのポインタ。
+
+## 例外
+
+要求されたアライメントでサイズ`nbytes`のメモリを確保できない場合、例外が送出される。
+
+## 例
+```cpp example
+#include <iostream>
+#include <memory_resource>
+
+int main() {
+  constexpr int N = 10;
+
+  std::pmr::polymorphic_allocator<> alloc{};
+
+  //int型10個分の領域をデフォルトアライメントで確保
+  void* vp = alloc.allocate_bytes(sizeof(int) * N, alignof(int));
+
+  //確保したメモリ領域へのポインタを所望の型のものにキャスト
+  int* p = static_cast<int*>(vp);
+
+  //確保したメモリ領域にintのオブジェクトを構築（コンストラクタ呼び出し）
+  for (int i = 0; i < N; ++i) {
+    alloc.construct(p+i, i);
+  }
+
+
+  std::cout << "address : " << vp << std::endl;
+
+  for (int i = 0; i < N; ++i) {
+    std::cout << p[i] << "\n";
+  }
+
+
+  //領域上のオブジェクトを破棄（デストラクタ呼び出し）
+  for (int i = 0; i < N; ++i) {
+    alloc.destroy(p+i);
+  }
+
+  //確保したメモリ領域を解放
+  alloc.deallocate_bytes(vp, N, alignof(int));
+}
+```
+* allocate_bytes[color ff0000]
+* construct[link construct.md]
+* destroy[link destroy.md]
+* deallocate_bytes[link deallocate_bytes.md]
+
+### 出力例（GCC9.2）
+```
+address : 0x1c38150
+0
+1
+2
+3
+4
+5
+6
+7
+8
+9
+```
+
+## バージョン
+### 言語
+- C++20
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): 9.1
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+## 関連項目
+- [`memory_resource::allocate`](/reference/memory_resource/memory_resource/allocate.md)
+
+## 参照
+- [P0339R6 polymorphic_allocator<> as a vocabulary type](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0339r6.pdf) 

reference/memory_resource/polymorphic_allocator/allocate_object.md

@@ -0,0 +1,107 @@
+# allocate_object
+* memory_resource[meta header]
+* function[meta id-type]
+* std::pmr[meta namespace]
+* polymorphic_allocator[meta class]
+* cpp17[meta cpp]
+
+```cpp
+template <class T>
+T* allocate_object(size_t n = 1);
+```
+
+## 概要
+
+指定された個数の`T`型の配列として十分なメモリを確保する。
+
+## 引数
+
+- `n` -- 確保する領域の数、バイト数ではなく配列の要素数相当
+
+## 効果
+
+以下と等価。
+
+```cpp
+return static_cast<T*>(this->allocate_bytes(n*sizeof(T), alignof(T)));
+```
+* allocate_bytes[link allocate_bytes.md]
+
+## 戻り値
+確保した領域の先頭へのポインタ。
+
+## 例外
+
+[`SIZE_MAX`](/reference/cstdint/size_max.md) `/ sizeof(T) < n`である場合、[`std::length_error`](/reference/stdexcept.md)例外を送出する
+
+## 備考
+
+型`T`は引数から推論することができないため、明示的に指定する必要がある。
+
+## 例
+```cpp example
+#include <iostream>
+#include <memory_resource>
+
+int main() {
+
+  constexpr int N = 10;
+
+  std::pmr::polymorphic_allocator<> alloc{};
+
+  //int型10個分の領域を確保
+  int* p = alloc.allocate_object<int>(N);
+
+  //確保した領域にintのオブジェクトを構築
+  for (int i = 0; i < N; ++i) {
+    alloc.construct(p+i, i);
+  }
+
+
+  for (int i = 0; i < N; ++i) {
+    std::cout << p[i] << "\n";
+  }
+
+
+  //領域上のオブジェクトを破棄
+  for (int i = 0; i < N; ++i) {
+    alloc.destroy(p+i);
+  }
+
+  //確保したメモリ領域を解放
+  alloc.deallocate_object(p, N);
+}
+```
+* allocate_object[color ff0000]
+* construct[link construct.md]
+* destroy[link destroy.md]
+* deallocate_object[link deallocate_object.md]
+
+### 出力
+```
+0
+1
+2
+3
+4
+5
+6
+7
+8
+9
+```
+
+## バージョン
+### 言語
+- C++20
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): 9.1
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+## 関連項目
+- [`allocate_bytes`](/reference/memory_resource/polymorphic_allocator/allocate_bytes.md)
+
+## 参照
+- [P0339R6 polymorphic_allocator<> as a vocabulary type](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0339r6.pdf)