From 3a81c45e19609fd1d4984a450d9138e9dfde347e Mon Sep 17 00:00:00 2001 From: Gordon Date: Mon, 8 Oct 2018 14:05:26 +0100 Subject: [PATCH] Issue #41: Make minor changes based on feedback. --- affinity/cpp-20/d0796r3.md | 45 +++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/affinity/cpp-20/d0796r3.md b/affinity/cpp-20/d0796r3.md index c2d7fff..0e004f9 100644 --- a/affinity/cpp-20/d0796r3.md +++ b/affinity/cpp-20/d0796r3.md @@ -305,13 +305,13 @@ Below *(Figure 2)* is an example of what a typical **system topology** could loo An `execution_resource` is a lightweight structure which identifies a particular **execution resource** within a snapshot of the **system topology**. It can be queried for a name via `name`. -An `execution_resource` object can be queried for a pointer to it's parent `execution_resource` via `member_of`, and can also iterate over it's children `execution_resource`s via `begin` and `end` or access a particular child via `operator[]`. +An `execution_resource` object can be queried for a pointer to its parent `execution_resource` via `member_of`, and can also iterate over its children `execution_resource`s via `begin` and `end` or access a particular child via `operator[]`. An `execution_resource` object can also be queried for the amount concurrency it can provide, the total number of **threads of execution** supported by the associated **execution resource**. An `execution_resource` object can be queried for a pointer to the root `memory_resource` representing the **memory resource** which the associated **execution resource** can access via `memory_resource`. -> [*Note:* There may be a number of **memory resources** which an **execution resource** can access, but the `memory_resource` pointer returned from `memory_resource` should represent the most course grained of these. We may want to expand on this interface in the future. *--end note*] +> [*Note:* There may be a number of **memory resources** which an **execution resource** can access, but the `memory_resource` pointer returned from `memory_resource` should represent the most coarse grained of these. We may want to expand on this interface in the future. *--end note*] Below *(Listing 3)* is an example of iterating over every **execution resource** within the **system topology**. @@ -335,7 +335,7 @@ int main(int argc, char * argv[]) { An `memory_resource` is a lightweight structure which inherits from `pmr::memory_resource` and identifies a particular **memory resource** within a snapshot of the **system topology**. It can be queried for a name via `name`. -A `memory_resource` object can be queried for a pointer to it's parent `memory_resource` via `member_of`, and can also iterate over it's children `memory_resource`s via `begin` and `end` or access a particular child via `operator[]`. +A `memory_resource` object can be queried for a pointer to its parent `memory_resource` via `member_of`, and can also iterate over its children `memory_resource`s via `begin` and `end` or access a particular child via `operator[]`. An allocator capable of allocating memory in the memory region of the **memory resource** represented by a `memory_resource` object by constructing a `pmr::polymorphic_allocator` from the `memory_resource` object. @@ -343,7 +343,7 @@ An allocator capable of allocating memory in the memory region of the **memory r The `affinity_query` class template provides an abstraction of the relative affinity between an `execution_resource` and a `memory_resource` for a particular `affinity_operation` and `affinity_metric`. The `affinity_query` takes the `affinity_operation` and `affinity_metric` as template parameters, and is constructed from an `execution_resource` and a `memory_resource`. -An `affinity_query` is not generally not meaningful on its own. Instead, users are meant to compare two `affinity_query`s via comparison operators, in order to get a relative magnitude of affinity. If necessary, the underlying value of an `affinity_query` can be queried through `native_affinity`, though the return value of this is implementation defined. +An `affinity_query` is not generally meaningful on its own. Instead, users are meant to compare two `affinity_query`s via comparison operators, in order to get a relative magnitude of affinity. If necessary, the underlying value of an `affinity_query` can be queried through `native_affinity`, though the return value of this is implementation defined. Below *(listing 4)* is an example of how to query the relative affinity between an `execution_resource` and a `memory_resource`. @@ -384,24 +384,25 @@ When creating an `execution_context` from a given `execution_resource`, the exec ```cpp auto systemResource = std::this_system::discover_topology(); -/* find_socket_resource is a user-defined function that finds a resource that is a CPU socket in the given resource list */ +// find_socket_resource is a user-defined function that finds a resource that is +// a CPU socket in the given resource list auto socket = find_socket_resource(systemResource); -/* Create an execution_context and executor associated with the CPU socket */ -execution_context context{socket} +// Create an execution_context and executor associated with the CPU socket +execution_context context{socket}; auto executor = context.executor(); -/* Create an allocator from the memory resource associate with the GPU socket */ +// Create an allocator from the memory resource associated with the GPU socket pmr::polymorphic_allocator alloc{socket.memory_resource()}; pmr::vector vec(100, alloc); -std::generate(par.on(executor), std::begin(vec), std::end(vec), std::rand); +std::generate(par.on(executor), std::begin(vec), std::end(vec), genFunc); ``` *Listing 6: Example of executing and allocating with affinity* -The construction of an `execution_context` on an `execution_resource` 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. +The construction of an `execution_context` on an `execution_resource` 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 required to guarantee the binding of execution agents. -Only developers that care about resource placement need to care about obtaining executorsfrom the correct `execution_context` object. Existing code for vectors and STL (including the Parallel STL interface) remains unaffected. +Only developers that care about resource placement need to care about obtaining executors 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`. @@ -506,7 +507,7 @@ The `execution_resource` which underlies the current thread of execution can be ~execution_context(); - const execution_resource &resource() const noexcept; + execution_resource &resource() const noexcept; executor_type executor() const; @@ -544,13 +545,13 @@ The `execution_resource` which underlies the current thread of execution can be /* This system */ namespace this_system { - const execution_resource discover_topology(); + execution_resource discover_topology(); } /* This thread */ namespace this_thread { - const std::experimental::execution::execution_resource get_resource() noexcept; + std::experimental::execution::execution_resource get_resource() noexcept; } } // experimental @@ -587,11 +588,11 @@ The `execution_resource` class provides an abstraction over an **execution resou iterator -*Requires:* `iterator` to model `RandomAccessIterator` with the value type `execution_resource::value_type`. +*Requires:* `iterator` satisfies the `Cpp17RandomAccessIterator` requirements and `is_same_v::value_type, execution_resource::value_type>` is well-formed and resolves to `true`. const_iterator -*Requires:* `const_iterator` to model `RandomAccessIterator` with the value type `execution_resource::value_type`. +*Requires:* `const_iterator` satisfies the `Cpp17RandomAccessIterator` requirements and `is_same_v::value_type, execution_resource::value_type>` is well-formed and resolves to `true`. ### `execution_resource` constructors @@ -642,7 +643,7 @@ The `execution_resource` class provides an abstraction over an **execution resou ## Class `memory_resource` -The `memory_resource` class provides an abstraction which represents a **memory resource**, that can allocate memory. A `memory_resource` can represent further `memory_resource`s. We say that these `ememory_resource`s are *members of* this `memory_resource`. +The `memory_resource` class provides an abstraction which represents a **memory resource**, that can allocate memory. A `memory_resource` can represent further `memory_resource`s. We say that these `memory_resource`s are *members of* this `memory_resource`. The `memory_resource` class must inherit from the `pmr::memory_resource` class. @@ -652,11 +653,11 @@ The `memory_resource` class must inherit from the `pmr::memory_resource` class. iterator -*Requires:* `iterator` to model `RandomAccessIterator` with the value type `memory_resource::value_type`. +*Requires:* `iterator` satisfies the `Cpp17RandomAccessIterator` requirements and `is_same_v::value_type, execution_resource::value_type>` is well-formed and resolves to `true`. const_iterator -*Requires:* `const_iterator` to model `RandomAccessIterator` with the value type `memory_resource::value_type`. +*Requires:* `const_iterator` satisfies the `Cpp17RandomAccessIterator` requirements and `is_same_v::value_type, execution_resource::value_type>` is well-formed and resolves to `true`. ### `memory_resource` constructors @@ -725,7 +726,7 @@ The `execution_context` class provides an abstraction for managing a number of l ### `execution_context` operators - const execution_resource &resource() const noexcept; + execution_resource &resource() const noexcept; *Returns:* A const-reference to the *contained resource*. @@ -784,7 +785,7 @@ The `affinity_query` class template provides an abstraction for a relative affin The free function `this_system::discover_topology` is provided for discovering the **system topology**. - const execution_resource discover_topology(); + execution_resource discover_topology(); *Returns:* An `execution_resource` object exposing the **system execution resource**. @@ -798,7 +799,7 @@ The free function `this_system::discover_topology` is provided for discovering t The free function `this_thread::get_resource` is provided for retrieving the `execution_resource` underlying the current thread of execution. - const std::experimental::execution::execution_resource get_resource() noexcept; + std::experimental::execution::execution_resource get_resource() noexcept; *Returns:* The `execution_resource` underlying the current thread of execution.