Issue #33: Add wording for high-level interface.

* Introduce `this_thread::bind` & `this_thread::unbind`.
* Introduce high-level interface `bulk_execution_affinity` properties.

Author: Gordon

affinity/cpp-20/d0796r2.md

@@ -14,6 +14,11 @@
 
 # Changelog
 
+### P0796r2 (RAP)
+
+* Introduce `this_thread::bind` & `this_thread::unbind` for binding a thread of execution to an execution resource.
+* Introduce high-level interface for execution binding via executor properties.
+
 ### P0796r1 (JAX)
 
 * Introduce proposed wording.
@@ -170,6 +175,43 @@ This feature could be easily scaled to heterogeneous and distributed systems, as
 
 In this paper we propose an interface for querying and representing the execution resources within a system, queurying the relative affinity metric between those execution resources, and then using those execution resources to allocate memory and execute work with affinity to the underlying hardware. The interface described in this paper builds on the existing initerface for executors and execution contexts defined in the executors proposal [[22]][p0443r4].
 
+### Interface grandularity
+
+In this paper we propose both a low-level interface and a high-level interface:
+* The low-level interface cosnsists of mechanisms for discovering detailed information about a system's topology and affinity properties which can be utilised to hand optimise parallel applications and libraries for the best performance. The low-level interface has high granularity and is aimed at users who have a high knowledge of the system architecture.
+* The high-level interface consists of policies which describe desired behaviour when using parallel algorithms or libraries. The high-level interface has low granularity and is aimed at users who may have little or no knowledge of the system architecture.
+
+## High-level interface
+
+The high-level interface is a polcy-based design which utilises the executor property mechanism to provide additional affinity based requirements on executors.
+
+### Bulk execution affinity
+
+In this paper we propose an executor property group called `bulk_execution_affinity` which contains the sub properties `none`, `balanced`, `scatter` or `compact`. Each of these properties, if applied to an *executor* enforce a particular guarantee of execution agent binding to the *execution resources* associated with the *executor* in a partuclar pattern:
+* **none** makes no guarantee that *execution agents* created by the *executor* will be bound to specific *execution resources*.
+* **balanced** guarantees that *execution agents* created by the executor will be bound to the *execution resources* associated with the *executor* close together in sequence but with an even distribution across the *execution resources*.
+* **scatter** guarantees that *execution agents* created by the executor will be bound to the *execution resources* associated with the *executor* distributed with each *execution agent* far from each other *execution agent* in sequence.
+* **compact** guarantees that *execution agents* created by the executor will be bound to the *execution resources* associated with the *executor* close together in sequence.
+
+Below *(Listing 2)* is an example of executing a parallel task over 8 threads using `bulk_execute`, with the affinity binding `bulk_execution_affinity.scatter`.
+
+```cpp
+{
+  auto exec = executionContext.executor();
+
+  auto affExec = execution::require(exec, execution::bulk,
+    execution::bulk_execution_affinity.scatter);
+
+  affExec.bulk_execute([](std::size_t i, shared s) {
+    func(i);
+  }, 8, sharedFactory);
+}
+
+```
+*Listing 2: Example of using the bulk_execution_affinity property*
+
+## Low-level interface
+
 ### Execution resources
 
 An `execution_resource` is a light weight structure which acts as an identifier to particular piece of hardware within a system. It can be queried for whether it can allocate memory via `can_place_memory` and whether it can execute work via `can_place_agents`, and for it's name via `name`. An `execution_resource` can also represent other `execution_resource`s, these are refered to as being *members of* that `execution_resource` and can be queried via `resources`. Additionally the `execution_resource` which another is a *member of* can be queried vis `member_of`. An `execution_resource` can also be queried for the concurrency it can provide; the total number of *threads of execution* supported by that *execution_resource* and all resources it represents.
@@ -182,7 +224,7 @@ An `execution_resource` is a light weight structure which acts as an identifier
 
 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.
 
-Below *(Listing 2)* is an example of iterating over the system level resources and priniting out it's capabilities.
+Below *(Listing 3)* is an example of iterating over the system level resources and priniting out it's capabilities.
 
 ```cpp
 for (auto res : execution::this_system::resources()) {
@@ -192,13 +234,13 @@ for (auto res : execution::this_system::resources()) {
     std::cout << res.concurrency() << `\n`;
 }
 ```
-*Listing 2: Example of querying all the system level execution resources*
+*Listing 3: Example of querying all the system level execution resources*
 
 ### 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.
 
-Below *(listing 3)* is an example of how you can query the relative affinity between two `execution_resource`s.
+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();
@@ -212,15 +254,15 @@ auto relativeLatency02 = execution::affinity_query<execution::affinity_operation
 
 auto relativeLatency = relativeLatency01 > relativeLatency02;
 ```
-*Listing 3: Example of querying affinity between two `execution_resource`s.*
+*Listing 4: Example of querying affinity between two `execution_resource`s.*
 
 > [*Note:* This interface for querying relative affinity is a very low-level interface designed to be abstracted by libraries and later affinity policies. *--end note*]
 
 ### 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. An `execution_context` can then provide an executor for executing work and an allocator or polymorphic memory resource for allocating memory. The `execution_context` is constructed with an `execution_resource`, the `execution_context` then executes work or allocates memory for that `execution_resource` and an `execution_resource` that it represents.
 
-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.
+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();
@@ -235,11 +277,9 @@ for (auto res : systelLevelResource.resources()) {
     std::cout << res.name()  << `\n`;
 }
 ```
-*Listing 4: Example of constructing an execution context from an execution resource*
+*Listing 5: Example of constructing an execution context from an execution resource*
 
-### Binding execution and allocation to 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)*.
+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();
@@ -252,14 +292,20 @@ auto socketAllocator = eC.allocator(); // Retrieve an allocator to the closest m
 std::vector<int, decltype(socketAllocator)> v1(100, socketAllocator);
 std::generate(par.on(executor), std::begin(v1), std::end(v1), std::rand);
 ```
-*Listing 5: Example of allocating with affinity to an execution resource*
+*Listing 6: Example of allocating with affinity to an execution resource*
 
 The construction of an `execution_context` on a component implies affinity (where possible) to the given resource. This guarantees that all executors created from that `execution_context` can access the resources and the internal data structures requires to guarantee the placement of the processor.
 
 Only developers that care about resource placement need to care about obtaining executors and allocations from the correct `execution_context` object. Existing code for vectors and STL (including the Parallel STL interface) remains unaffected.
 
 If a particular policy or algorithm requires to access placement information, the resources associated with the passed executor can be retrieved via the link to the `execution_context`.
 
+### Binding to execution
+
+A *thread of execution* can be bound to a particular `execution_resource` for a particular *execution agent* by calling `this_thread::bind`. After which point the *execution resource* returned by `this_thread::get_resource` must be equal to the `execution_resource` provided to `this_thread::bind`. Subsequently a *thread of execution* can be unbound by calling `this_thread::unbind`.
+
+> [*Note:* Binding *threads of execution* can provide performance benefits when used in a way which compliments the application, however incorrect usage can lead to denial of service and therefore can cause loss of performance. *--end note*]
+
 ## Header `<execution>` synopsis
 
     namespace std {
@@ -349,11 +395,16 @@ If a particular policy or algorithm requires to access placement information, th
       std::vector<execution_resource> resources() noexcept;
     }
 
+    namespace this_thread {
+        bool bind(executon_resource) noexcept;
+        bool unbind(executon_resource) noexcept;
+    }
+
     }  // execution
     }  // experimental
     }  // std
 
-*Listing 6: Header synopsis*
+*Listing 7: Header synopsis*
 
 ## Class `execution_resource`
 
@@ -515,6 +566,20 @@ The free function `this_system::resources` is provided for retrieving the `execu
 
 > [*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*]
 
+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_reosurce`.
+
+    bool bind(executon_resource) noexcept;
+
+*Returns:* `true` if the requested binding was successful, otherwise `false`.
+
+*Effects:* If successful, binds the current *thread of execution* to the specified `execution_resource`.
+
+    bool unbind(executon_resource) noexcept;
+
+*Returns:* `true` if the requested unbinding was successful, otherwise `false`.
+
+*Effects:* If successful, unbinds the current *thread of execution* from the specified `execution_resource`.
+
 # Future Work
 
 ## Migrating data from memory allocated in one partition to another