CP013: Add minor modifications to D0796r1.

* Add changelog.
* Add proposed wording.
* Add Chapel, X10 and UPC++ to the list of background research.
* Add inline links to references.

Author: Gordon Brown

affinity/cpp-20/d0796r1.md

@@ -12,6 +12,12 @@
 
 **Reply to: michael@codeplay.com**
 
+# Changelog
+
+### Revision 1
+
+* Introduce proposed wording.
+
 # Abstract
 
 This paper provides an initial meta-framework for the drives toward memory affinity for C++, given the direction from Toronto 2017 SG1 meeting that we should look towards defining affinity for C++ before looking at inaccessible memory as a solution to the separate memory problem towards supporting heterogeneous and distributed computing.
@@ -62,18 +68,20 @@ The goal was that this would enable scaling up for heterogeneous and distributed
 
 The problem of effectively partitioning a system’s topology is one which has been so for some time, and there are a range of third party libraries / standards which provides APIs to solve the problem. In order to standardise this process for the C++ standard we must carefully look at all of these. Below is a list of the libraries and standards which define an interface for affinity:
 
-Portable Hardware Locality: https://www.open-mpi.org/projects/hwloc/
-SYCL 1.2: https://www.khronos.org/registry/SYCL/specs/sycl-1.2.pdf
-OpenCL 2.2: https://www.khronos.org/registry/OpenCL/specs/opencl-2.2.pdf
-HSA: http://www.hsafoundation.com/standards/
-OpenMP 4.0: https://www.cct.lsu.edu/mardigras14/abstracts#Wong
-cpuaff: https://github.com/dcdillon/cpuaff
-OpenMP 5.0: http://www.openmp.org/wp-content/uploads/openmp-TR5-final.pdf
-Persistent Memory Programming: http://pmem.io/
-MEMKIND: https://github.com/memkind/memkind
-Solaris pbind(): https://docs.oracle.com/cd/E26502_01/html/E29031/pbind-1m.html
-Linux sched_setaffinity(): https://linux.die.net/man/2/sched_setaffinity
-Windows SetThreadAffinityMask(): https://msdn.microsoft.com/en-us/library/windows/desktop/ms686247(v=vs.85).aspx
+* [Portable Hardware Locality][hwloc]
+* [SYCL 1.2][sycl-1-2-1]
+* [OpenCL 2.2][opencl-2-2]
+* [HSA][HSA]
+* [OpenMP 5.0][openmp-5]
+* [cpuaff][cpuaff]
+* [Persistent Memory Programming][pmem]
+* [MEMKIND][memkid]
+* [Solaris pbind()][solaris-pbind]
+* [Linux sched_setaffinity()][linux-sched-setaffinity]
+* [Windows SetThreadAffinityMask()][windows-set-thread-affinity-mask]
+* [Chapel][chapel]
+* [X10][x10]
+* [UPC++][upc++]
 
 Libraries such as the Portable Hardware Locality (hwloc) [9] provide a low level of hardware abstraction and offer a solution for the portability problem by supporting many platforms and operating systems. This and similar approaches may provide detailed hardware information in a tree-like structure. However, even some current systems cannot be represented correctly by a tree, where the number of hops between two sockets vary between socket pairs [14].
 
@@ -94,6 +102,66 @@ There are some additional challenges which we have been investigating but are no
 * Migrating data from memory allocated in one partition to another
 * Defining memory placement algorithms or policies
 
+
+## Proposed Wording
+
+### Header synopsis
+
+```cpp
+namespace std {
+namespace experimental {
+namespace execution {
+
+/* Execution resource */
+
+struct execution_resource {
+
+  execution_resource() = delete;
+  execution_resource(const execution_resource &) = delete;
+  execution_resource(execution_resource &&) = delete;
+  execution_resource &operator=(const execution_resource &) = delete;
+  execution_resource &operator=(execution_resource &&) = delete;
+
+  size_t concurrency() const noexcept;
+  size_t partition_size() const noexcept;
+
+  const execution_resource &partition(size_t i) const noexcept;
+  const execution_resource &member_of() const noexcept;
+
+  std::string name() const noexcept;
+
+  bool can_place_memory() const noexcept;
+  bool can_place_agent() const noexcept;
+
+};
+
+/* Execution context */
+
+struct execution_context {
+
+  using executor_type = __unspecfied__;
+
+  template <typename ExecutionResource>
+  execution_context(ExecutionResource &&execResource);
+
+  execution_resource &resource();
+
+  executor_type executor() noexcept;
+
+};
+
+/* This system */
+
+namespace this_system {
+  execution_resource &resource();
+}
+
+}  // execution
+}  // experimental
+}  // std
+```
+*Listing 2: Header synopsis*
+
 ### Querying a System’s Topology
 
 The first task in allowing C++ applications to leverage memory locality is to provide the ability to query a **system** for its **resource topology** (commonly represented as a tree or graph) and traverse its **execution resources**.
@@ -157,7 +225,7 @@ struct execution_resource {
 
 };
 ```
-*Listing 2: Proposed extended execution resource interface*
+*Listing 3: Proposed extended execution resource interface*
 
 The interface described above describes an execution resource as an object which cannot be user constructed, copied or moved, only referenced. It provides an interface for recursively querying the partitions and concurrency of it’s child execution resources via the member functions `concurrency`, `partition_size` and `partition` and it’s parent execution resource via the member function `member_of`. This interface is designed to match the design of `thread_execution_resource_t` [8]. Note that the resource is not limited to be an **execution resource**, but also a general resource where no execution can take place but memory can be allocated such as off-chip memory.
 
@@ -185,7 +253,7 @@ namespace std::this_system {
   execution_resource &resource();
 }
 ```
-*Listing 3: Interface for querying the execution resources available within a system*
+*Listing 4: Interface for querying the execution resources available within a system*
 
 The **resource** function in the `this_system` namespace will return the root **execution resource** of the current system.
 
@@ -198,7 +266,7 @@ for (int i = 0 ; i < partition_size(); i++) {
     std::cout << resource.partition(i).name()  << std::endl;
 }
 ```
-*Listing 4: Example of querying the execution resources available within a system*
+*Listing 5: Example of querying the execution resources available within a system*
 
 | Straw Poll |
 |------------|
@@ -217,7 +285,7 @@ struct execution_context {
   ...
 };
 ```
-*Listing 5: Extension to execution_context interface*
+*Listing 6: Extension to execution_context interface*
 
 The **execution context** constructor described above allows constructing an **execution context** from any **execution resource** within a **system’s resource topology**. The constructed **execution context** can then execute work on any resource under that **execution resource**.
 
@@ -238,7 +306,7 @@ for (int i = 0; i < resource.partition_size(); i++) {
     std::cout << resource.partition(i).name()  << std::endl;
 }
 ```
-*Listing 6: Example of constructing an execution context from an execution resource*
+*Listing 7: Example of constructing an execution context from an execution resource*
 
 | Straw Poll |
 |------------|
@@ -399,3 +467,22 @@ Euro-Par 2011 Parallel Processing: 17th International
 
 [22] Portable Hardware Locality Istopo
 https://www.open-mpi.org/projects/hwloc/lstopo/
+
+
+[//]: Links
+
+[hwloc]: https://www.open-mpi.org/projects/hwloc/
+[sycl-1-2-1]: https://www.khronos.org/registry/SYCL/specs/sycl-1.2.1.pdf
+[opencl-2-2]: https://www.khronos.org/registry/OpenCL/specs/opencl-2.2.pdf
+[HSA]: http://www.hsafoundation.com/standards/
+[openmp-4]: https://www.cct.lsu.edu/mardigras14/abstracts#Wong
+[openmp-5]: http://www.openmp.org/wp-content/uploads/openmp-TR5-final.pdf
+[cpuaff]: https://github.com/dcdillon/cpuaff
+[pmem]: http://pmem.io/
+[memkid]: https://github.com/memkind/memkind
+[solaris-pbind]: https://docs.oracle.com/cd/E26502_01/html/E29031/pbind-1m.html
+[linux-sched-setaffinity]: https://linux.die.net/man/2/sched_setaffinity
+[windows-set-thread-affinity-mask]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms686247(v=vs.85).aspx
+[chapel]: https://chapel-lang.org/
+[x10]: http://x10-lang.org/
+[upc++]: https://bitbucket.org/berkeleylab/upcxx/wiki/Home