Merge branch 'master' into patch-6

Author: AerialMantis

affinity/cpp-20/d0796r2.md

@@ -14,12 +14,16 @@
 
 # Changelog
 
+### P0796r2 (RAP)
+
+* Introduced a free function for retrieving the execution resource underlying the current thread of execution.
+
 ### P0796r1 (JAX)
 
 * Introduce proposed wording.
 * Based on feedback from SG1, introduce a pair-wise interface for querying the relative affinity between execution resources.
 * Introduce an interface for retrieving an allocator or polymorphic memory resource.
-* Based on feedback from SG1, remove requirement for a hierarchical system topology structure, which doesn't require a root resouce.
+* Based on feedback from SG1, remove requirement for a hierarchical system topology structure, which doesn't require a root resource.
 
 ### P0796r0 (ABQ)
 
@@ -180,12 +184,12 @@ An `execution_resource` is a lightweight structure which acts as an identifier t
 
 ### System topology
 
-The system topology is made up of a number of system-level `execution_resource`s, which can be queried through `this_system::resource` which returns a `std::vector`. A run-time library may initialize the `execution_resources` available within the system dynamically. However, this must be done before `main` is called, given that after that point, the system topology may not change.
+The system topology is made up of a number of system-level `execution_resource`s, which can be queried through `this_system::get_resources` which returns a `std::vector`. A run-time library may initialize the `execution_resource`s available within the system dynamically. However, this must be done before `main` is called, given that after that point, the system topology may not change.
 
 Below *(Listing 2)* is an example of iterating over the system-level resources and printing out their capabilities.
 
 ```cpp
-for (auto res : execution::this_system::resources()) {
+for (auto res : execution::this_system::get_resources()) {
     std::cout << res.name()  `\n`;
     std::cout << res.can_place_memory() << `\n`;
     std::cout << res.can_place_agents() << `\n`;
@@ -194,14 +198,18 @@ for (auto res : execution::this_system::resources()) {
 ```
 *Listing 2: Example of querying all the system level execution resources*
 
+### Current resource
+
+The `execution_resource` which underlies the current thread of execution can be queried through `this_thread::get_resource`.
+
 ### Querying relative affinity
 
 The `affinity_query` class template provides an abstraction for a relative affinity value between two `execution_resource`s. This value depends on a particular `affinity_operation` and `affinity_metric`. As a result, the `affinity_query` is templated on `affinity_operation` and `affinity_metric`, and is constructed from two `execution_resource`s. An `affinity_query` is not meant to be meaningful on its own. Instead, users are meant to compare two queries with comparison operators, in order to get a relative magnitude of affinity. If necessary, the value of an `affinity_query` can also be queried through `native_affinity`, though the return value of this is implementation defined.
 
 Below *(listing 3)* is an example of how to query the relative affinity between two `execution_resource`s.
 
 ```cpp
-auto systemLevelResources = execution::this_system::resources();
+auto systemLevelResources = execution::this_system::get_resources();
 auto memberResources = systemLevelResources.resources();
 
 auto relativeLatency01 = execution::affinity_query<execution::affinity_operation::read,
@@ -223,15 +231,15 @@ The `execution_context` class provides an abstraction for managing a number of l
 Below *(Listing 4)* is an example of how this extended interface could be used to construct an *execution context* from an *execution resource* which is retrieved from the *system’s resource topology*. Once an *execution context* is constructed it can then still be queried for its *execution resource*, and that *execution resource* can be further partitioned.
 
 ```cpp
-auto &resources = execution::this_system::resources();
+auto &resources = execution::this_system::get_resources();
 
 execution::execution_context execContext(resources[0]);
 
-auto &systelLevelResource = execContext.resource();
+auto &systemLevelResource = execContext.resource();
 
 // resource[0] should be equal to execResource
 
-for (auto res : systelLevelResource.resources()) {
+for (auto res : systemLevelResource.resources()) {
     std::cout << res.name()  << `\n`;
 }
 ```
@@ -242,11 +250,11 @@ for (auto res : systelLevelResource.resources()) {
 When creating an `execution_context` from a given `execution_resource`, the executors and allocators associated with it are bound to that `execution_resource`. For example, when creating an `execution_resource` from a CPU socket resource, all executors associated with the given socket will spawn execution agents with affinity to the socket partition of the system *(Listing 5)*.
 
 ```cpp
-auto cList = std::execution::this_system::resources();
+auto cList = std::execution::this_system::get_resources();
 // FindASocketResource is a user-defined function that finds a 
 // resource that is a CPU socket in the given resource list
 auto& socket = findASocketResource(cList);
-execution_contexteC{socket} // Associated with the socket
+execution_contextC{socket} // Associated with the socket
 auto executor = eC.executor(); // By transitivity, associated with the socket too
 auto socketAllocator = eC.allocator(); // Retrieve an allocator to the closest memory node
 std::vector<int, decltype(socketAllocator)> v1(100, socketAllocator);
@@ -343,13 +351,20 @@ If a particular policy or algorithm requires to access placement information, th
 
     };
 
+    }  // execution
+
     /* This system */
 
     namespace this_system {
       std::vector<execution_resource> resources() noexcept;
     }
 
-    }  // execution
+    /* This thread */
+
+    namespace this_thread {
+      std::experimental::execution::execution_resource get_resource() noexcept;
+    }
+
     }  // experimental
     }  // std
 
@@ -496,7 +511,7 @@ The `affinity_query` class template provides an abstraction for a relative affin
     friend expected<size_t, error_type> operator>=(const affinity_query&, const affinity_query&);
 
 *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 successful, 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*]
@@ -505,16 +520,26 @@ The `affinity_query` class template provides an abstraction for a relative affin
 
 ## Free functions
 
-The free function `this_system::resources` is provided for retrieving the `execution_resource`s which encapsulate the hardware platforms available within the system. We refer to these resources as the *system level resources*.
+### `this_system::get_resources`
+
+The free function `this_system::get_resources` is provided for retrieving the `execution_resource`s which encapsulate the hardware platforms available within the system. We refer to these resources as the *system level resources*.
 
 	std::vector<execution_resource> resources() noexcept;
 
 *Returns:* An `std::vector` containing all *system level resources*.
 
-*Requires:* If `this_system::resources().size() > 0`, `this_system::resources()[0]` be the `execution_resource` use by `std::thread`. The value returned by `this_system::resources()` be the same at any point after the invocation of `main`.
+*Requires:* If `this_system::get_resources().size() > 0`, `this_system::get_resources()[0]` be the `execution_resource` use by `std::thread`. The value returned by `this_system::get_resources()` be the same at any point after the invocation of `main`.
 
 > [*Note:* Returning a `std::vector` allows users to potentially manipulate the container of `execution_resource`s after it is returned. We may want to replace this at a later date with an alternative type which is more restrictive, such as a range or span. *--end note*]
 
+### `this_thread::get_resource`
+
+The free function `this_thread::get_resource` is provided for retrieving the `execution_resource` underlying the current thread of execution.
+
+    std::experimental::execution::execution_resource get_resource() noexcept;
+
+*Returns:* The `execution_resource` underlying the current thread of execution.
+
 # Future Work
 
 ## Migrating data from memory allocated in one partition to another
@@ -545,7 +570,7 @@ We may wish to mirror the design of the executors proposal and have a generic qu
 
 ## Dynamic topology discovery
 
-The current proposal requires that all `execution_resource`s are initialized before `main` is called. This therefore does not permit an `execution_resource` to become available or go off-line at run time. We may wish to support this in the future, however this is outside of the scope of this paper.
+The current proposal requires that all `execution_resource`s are initialized before `main` is called. This therefore does not permit an `execution_resource` to become available or go off-line at run time. We may wish to support this in the future, however this is outside of the scope of this paper at the moment.
 
 | Straw Poll |
 |------------|