Issue #34: Introduce free function for retrieving a threads resource.

* Introduce the `this_thread::get_resource` free function for retrieving
the underlying execution resource of the current thread of execution.
* Rename `this_system::resources` to `this_system::get_resources` to be
more consistent with the current standard.
* Correct typos.

Author: Gordon Brown

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, introduced 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 light weight structure which acts as an identifier
 
 ### 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`. The `execution_resources` available within the system can be initialised dynamically by a runtime library, however must be done so before `main` is called, given that after that point the system topology cannot 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`. The `execution_resources` available within the system can be initialised dynamically by a runtime library, however must be done so before `main` is called, given that after that point the system topology cannot change.
 
 Below *(Listing 2)* is an example of iterating over the system level resources and priniting out it's 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, derived from a particular `affinity_operation` and `affinity_metric`. The `affinity_query` is templated by `affinity_operation` and `affinity_metric` and is constructed from two `execution_resource`s. An `affinity_query` does not mean much on it's own, instead a relative magnitude of affinity can be queried by using comparison operators. If nessesary the value of an `affinity_query` can also be queried through `native_affinity`, though the return value of this is implementation defined.
+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`. The `affinity_query` is templated by `affinity_operation` and `affinity_metric` and is constructed from two `execution_resource`s. An `affinity_query` does not mean much on it's own, instead a relative magnitude of affinity can be queried by using comparison operators. 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 you can 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 then 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
 
@@ -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, these are refered to 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, these are referred to as the *system level resources*.
 
 	std::vector<execution_resource> resources() noexcept;
 
 *Returns:* A 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 with an alternative type which is more restrictive at a later date such as a range. *--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