Merge branch 'master' into issue-33

Author: Gordon Brown

affinity/cpp-20/d0796r2.md

@@ -16,6 +16,7 @@
 
 ### P0796r2 (RAP)
 
+* Introduced a free function for retrieving the execution resource underlying the current thread of execution.
 * Introduce `this_thread::bind` & `this_thread::unbind` for binding and unbinding a thread of execution to an execution resource.
 * Introduce high-level interface for execution binding via executor properties.
 
@@ -24,7 +25,7 @@
 * 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)
 
@@ -224,12 +225,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 initialized 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 initialized 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 3)* is an example of iterating over the system level resources and printing 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`;
@@ -238,14 +239,18 @@ for (auto res : execution::this_system::resources()) {
 ```
 *Listing 3: 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 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 4)* 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,
@@ -267,15 +272,15 @@ The `execution_context` class provides an abstraction for managing a number of l
 Below *(Listing 5)* 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`;
 }
 ```
@@ -284,11 +289,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 6)*.
 
 ```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);
@@ -391,18 +396,23 @@ A *thread of execution* can be requested to bind to a particular `execution_reso
 
     };
 
+    }  // execution
+
     /* This system */
 
     namespace this_system {
       std::vector<execution_resource> resources() noexcept;
     }
 
+    /* This thread */
+
     namespace this_thread {
-        bool bind(execution_resource eR) noexcept;
-        bool unbind(execution_resource eR) noexcept;
+      std::experimental::execution::execution_resource get_resource() noexcept;
+
+      bool bind(execution_resource eR) noexcept;
+      bool unbind(execution_resource eR) noexcept;
     }
 
-    }  // execution
     }  // experimental
     }  // std
 
@@ -558,16 +568,20 @@ 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 referred 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::bind` & `this_thread::unbind`
+
 The free functions `this_thread::bind` and `this_thread::unbind` are provided for binding / unbinding the current *thread of execution* to / from a particular `execution_resource`.
 
     bool bind(execution_resource eR) noexcept;
@@ -586,6 +600,14 @@ The free functions `this_thread::bind` and `this_thread::unbind` are provided fo
 
 *Effects:* If successful, unbinds the current *thread of execution* from the specified `execution_resource`.
 
+### `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