CP013: Finish adding the new proposals.

* Minor fixes for typos.
* Have execution_context::memory_resource() return a reference instead
of a pointer.
* Add execution_context::allocator().
* Add execution_context::pmr_memory_resource_type alias.
* Fill in requirements for execution_resource, execution_context,
affinity_query and this_system::resources().

Author: Gordon Brown

affinity/cpp-20/d0796r1.md

@@ -37,7 +37,7 @@ One strategy to improve applications' performance, given the importance of affin
 
 Operating systems (OSes) traditionally take responsibility for assigning threads or processes to run on processing units. However, OSes may use high-level policies for this assignment that do not necessarily match the optimal usage pattern for a given application. Application developers must leverage the placement of memory and **placement of threads** for best performance on current and future architectures. For C++ developers to achieve this, native support for **placement of threads and memory** is critical for application portability. We will refer to this as the **affinity problem**. 
 
-The affinity problem is especially challenging for applications whose behavior changes over time or is hard to predict, or when different applications interfere with each other's performance. Today, most OSes already can group processing units according to their locality and distribute processes, while keeping threads close to the initial thread, or even avoid migrating threads and maintain first touch policy. Nevertheless, most pro  grams can change their work distribution, especially in the presence of nested parallelism.
+The affinity problem is especially challenging for applications whose behavior changes over time or is hard to predict, or when different applications interfere with each other's performance. Today, most OSes already can group processing units according to their locality and distribute processes, while keeping threads close to the initial thread, or even avoid migrating threads and maintain first touch policy. Nevertheless, most programs can change their work distribution, especially in the presence of nested parallelism.
 
 Frequently, data is initialized at the beginning of the program by the initial thread and is used by multiple threads. While automatic thread migration has been implemented in some OSes, migration may have high overhead. In an optimal case, the OS may automatically detect which thread access which data most frequently, or it may replicate data which is read by multiple threads, or migrate data which is modified and used by threads residing on remote locality groups. However, the OS often does a reasonable job, if the machine is not overloaded, if the application carefully used first-touch allocation, and if the program does not change its behavior with respect to locality.
 
@@ -128,10 +128,10 @@ There are some additional challenges which we have been investigating but are no
       ~execution_resource();
 
       size_t concurrency() const noexcept;
-      size_t partition_size() const noexcept;
 
-      const execution_resource &partition(size_t) const noexcept;
-      const execution_resource &member_of() const noexcept;
+      std::vector<resource> resources() const noexcept;
+
+      const execution_resource member_of() const noexcept;
 
       std::string name() const noexcept;
 
@@ -145,17 +145,23 @@ There are some additional challenges which we have been investigating but are no
     class execution_context {
      public:
 
-      using executor_type = __unspecfied__;
+      using executor_type = see-below;
+
+      using pmr_memory_resource_type = see-below;
+
+      using allocator_type = see-below;
 
-      execution_context(const execution_resource &);
+      execution_context(const execution_resource &) noexcept;
 
       ~execution_context();
 
       const execution_resource &resource() const noexcept;
 
-      executor_type executor() noexcept;
+      executor_type executor() const;
 
-      pmr::memory_resource *memory_resource() noexcept;
+      pmr_memory_resource_type &memory_resource() const;
+
+      allocator_type allocator() const;
 
     };
 
@@ -168,10 +174,10 @@ There are some additional challenges which we have been investigating but are no
     class affinity_query {
      public:
 
-      using native_affinity_type = __unspecified__;
-      using error_type = __unspecified__
+      using native_affinity_type = see-below;
+      using error_type = see-below
 
-      affinity_query(execution_resource &&, execution_resource &&);
+      affinity_query(execution_resource &&, execution_resource &&) noexcept;
 
       ~affinity_query();
 
@@ -200,110 +206,124 @@ There are some additional challenges which we have been investigating but are no
 
 ## Class `execution_resource`
 
-The `execution_resource` class provides an abstraction over a system's hardware capable of memory allocation, execution of light weight exeution agents or both.
+The `execution_resource` class provides an abstraction over a system's hardware capable of memory allocation, execution of light weight exeution agents or both. An `execution_resource` can represent further `execution_resource`s, these `execution_resource`s are said to be *members of* this `execution_resource`.
 
 > [*Note:* The `execution_resource` is required to be implemented such that the underlying software abstraction is initialised on when the `execution_resource` is constructed, maintained through reference counting and cleaned up on destruction of the final reference. *--end note*]
 
 ### `execution_resource` constructors
 
-    execution_resource() = delete;
+    execution_resource();
 
 > [*Note:* An implementation of `execution_resource` is permitted to provide non-public constructors to allow other objects to construct them. *--end note*]
 
 ### `execution_resource` assignment
 
-The `execution_resource` class is not `CopyConstructible` (C++Std [copyconstructible]).
-
     execution_resource(const execution_resource &);
     execution_resource(execution_resource &&);
     execution_resource &operator=(const execution_resource &);
     execution_resource &operator=(execution_resource &&);
 
 ### `execution_resource` destructor
 
-The `execution_resource` class is not `Destructible` (C++Std [destructible]).
-
-    ~execution_resource() = delete;
+    ~execution_resource();
 
 ### `execution_resource` operations
 
     size_t concurrency() const noexcept;
 
-*Returns:*
+*Returns:* The collective concurrency available to this resource. More pecifically, the number of *threads of execution* collectively available to this `execution_resource` and any resources which are *members of*, recursively.
 
-    size_t partition_size() const noexcept;
+    std::vector<resource> resources() const noexcept;
 
-*Returns:*
-
-    const execution_resource &partition(size_t) const noexcept;
-
-*Returns:*
+*Returns:* All `execution_resource`s which are *members of* this resource.
 
     const execution_resource &member_of() const noexcept;
 
-*Returns:*
+*Returns:* The `execution_resource` which this resource is a *member of*.
 
     std::string name() const noexcept;
 
-*Returns:*
+*Returns:* An implementation defined string.
 
     bool can_place_memory() const noexcept;
 
-*Returns:*
+*Returns:* If this resource is capable of allocating memory with affinity, 'true'.
 
     bool can_place_agent() const noexcept;
 
-*Returns:*
+*Returns:* If this resource is capable of execute with affinity, 'true'.
 
 ## Class `execution_context`
 
-The `execution_context` class provides an abstraction for managing a number of light weight execution agents executing work on an `execution_resource` and any `execution_resource`s encapsulated by it.
+The `execution_context` class provides an abstraction for managing a number of light weight execution agents executing work on an `execution_resource` and any `execution_resource`s encapsulated by it. The `execution_resource` which an `execution_context` encapsulates is refered to as the *contained resource*.
+
+### `execution_context` types
+
+    using executor_type = see-below;
+
+*Requires:* `executor_type` is an implementation defined class which satifies the general executor requires, as specified by P0443r5.
 
-### `execution_context` member aliases
+    using pmr_memory_resource_type = see-below;
 
-    using executor_type = __unspecfied__;
+*Requires:* `pmr_memory_resource_type` is an implementation defined class which inherits from `std::pmr::memory_resource`.
 
-*Requires:*
+    using allocator_type = see-below;
+
+*Requires:* `allocator_type` is an implementation defined allocator class.
 
 ### `execution_context` constructors
 
-    execution_context(const execution_resource &);
+    execution_context(const execution_resource &) noexcept;
+
+*Effects:* Constructs an `execution_context` with the provided resource as the *contained resource*.
 
 ### `execution_context` destructor
     
     ~execution_context();
 
+*Effects:* May or may not block to wait any work bveing executed on the *contained resource*.
+
 ### `execution_context` operators
 
     const execution_resource &resource() const noexcept;
 
-*Returns:*
+*Returns:* A const-reference to the *contained resource*.
 
     executor_type executor() noexcept;
 
-*Returns:*
+*Returns:* An executor of type `executor_type` capable of executing work with affinity to the *contained resource*.
+
+*Throws:* An exception `!this->resource().can_place_agents()`.
+
+    pmr::memory_resource &memory_resource() noexcept;
 
-    pmr::memory_resource *memory_resource() noexcept;
+*Returns:* A reference to a polymorphic memory resource of type `pmr_memory_resource_type` capable of allocating with affinity to the *contained resource*.
 
-*Returns:*
+*Throws:* If `!this->resource().can_place_memory()`.
+
+    allocator_type allocator() const;
+
+*Returns:* An allocator of type `allocator_type` capable of allocating with affinity to the *contained resource*.
+
+*Throws:* If `!this->resource().can_place_memory()`.
 
 ## Class template `affinity_query`
 
 The `affinity_query` class template provides an abstraction for a relative affinity value between two `execution_resource`s, derived from a particular `affinity_operation` and `affinity_metric`.
 
-### `affinity_query` member aliases
+### `affinity_query` types
 
-    using native_affinity_type = __unspecfied__;
+    using native_affinity_type = see-below;
 
-*Requires:*
+*Requires:* `native_affinity_type` is an implementation defined integral type capable of storing a native affinity value.
 
-    using error_type = __unspecfied__;
+    using error_type = see-below;
 
-*Requires:*
+*Requires:* `error_type` is an implementation defined integral type capable of storing the an error code value.
 
 ### `affinity_query` constructors
 
-    affinity_query(const execution_resource &, const execution_resource &);
+    affinity_query(const execution_resource &, const execution_resource &) noexcept;
 
 ### `affinity_query` destructor
 
@@ -317,22 +337,28 @@ The `affinity_query` class template provides an abstraction for a relative affin
 
 ### `affinity_query` comparisons
 
-    friend expected<size_t> operator==(const affinity_query&, const affinity_query&);
-    friend expected<size_t> operator!=const affinity_query&, const affinity_query&);
-    friend expected<size_t> operator<(const affinity_query&, const affinity_query&);
-    friend expected<size_t> operator>(const affinity_query&, const affinity_query&);
-    friend expected<size_t> operator<=(const affinity_query&, const affinity_query&);
-    friend expected<size_t> operator>=(const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator==(const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator!=const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator<(const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator>(const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator<=(const affinity_query&, const affinity_query&);
+    friend expected<size_t, error_type> operator>=(const affinity_query&, const affinity_query&);
 
-*Returns:*
+*Returns:* An `expected<size_t, error_type>` where,
+* if the affinity query was succesful, the value of type `size_t` represents the magnitude of the relative affinity;
+* if the affinity query was not successful, the error is an error of type `error_type` which represents the reason for affinity query failed.
+
+> [*Note:* An affinity query is permitted to fail if affinity between the two execution resources cannot be calculated for any reason, such as the resources are of different vendors or communication between the resources is not possible. *--end note*]
 
 > [*Note:* The comparison operators rely on the availability of the `expected` class template (see [P0323r4: std::expected][p0323r4]), if this does not become available then an alternative error/value construct will be adopted instead. *--end note*]
 
 ## Free functions
 
+The free function `this_system::resources` is provided for retrieving the `execution_resource`s which encapsualte the hardware platforms available within the system, these are refered to as the *system level resources*.
+
 	std::vector<execution_resource> resources() noexcept;
 
-*Returns:* A std::vector containing all system level resources.
+*Returns:* A std::vector containing all *system level resources*.
 
 *Requires:* If `resources().size() > 0`, `resources()[0]` be the `execution_resource` corroponding to the current thread of execution. The value returned by `resources()` be the same at any point after the invocation of `main`.