Completed draft of Resources subsection

Author: marcpaterno

doc/ch_conceptual_design/resources.rst

@@ -9,16 +9,17 @@ As mentioned in :numref:`ch_conceptual_design/algorithms:Algorithms`, the typica
 
 where the types :cpp:`P1, Pn...` represent data products, and the types :cpp:`Rm...` represent resources.
 
-Phlex calls *resources* the object that can be used by an algorithm to let the framework know that the algorithm requires access to a shared entity which is not semantically related to the data-product set hierarchy.
-Note that in the requirements that the word "resource" is sometimes used in a more general sense.
-In this section we are only referring to the specific kind of resource described above.
+.. note::
+  Phlex calls *resources* the object that can be used by an algorithm to let the framework know that the algorithm requires access to a shared entity which is not semantically related to the data-product set hierarchy.
+  Note that in the requirements that the word "resource" is sometimes used in a more general sense.
+  In this section we are only referring to the specific kind of resource described above.
 
 An example registration of an algorithm that requires both a data product and a resource is found in :numref:`ch_conceptual_design/hofs/observers:Observers`.
 The details of the registration code express to the framework which arguments correspond to data products and which correspond to resources :need:`DUNE 52`.
 They may be stateless objects (e.g. a resource that denotes that an algorithm requires the use of a specific thread-unsafe library) or stateful objects (e.g. a resource that denotes access to a GPU, when the platform on which the framework program is running contains several GPUs).
 Neither of these examples contain mutable state.
 Resources (unlike data products) may have mutable state accessible to the algorithm (e.g. a histogram instance that could be shared across multiple algorithms).
-For resources that are mutable, the framework ensures that two algorithms are not interacting with the resource at the same time.
+For resources that are thread-unsafe, the framework ensures that two algorithms are not interacting with the resource at the same time.
 The framework is responsible for efficiently scheduling algorithms based, in part, upon the availability of resources :need:`DUNE 50`.
 
 Examples of resources include:
@@ -34,20 +35,25 @@ Whereas data products have provenance associated with them, resources do not.
 Limited Resources
 -----------------
 
-.. todo::
+Some resources are used to indicate that an algorithm requires sole use of some program entity.
+One example of such an entity is a thread-unsafe library, where the framework must ensure that only one algorithm is interacting with that library at any time :need:`DUNE 45`, :need:`DUNE 145`.
+A second example of a limited resource is a fixed number of GPUs present on a particular platform, where Phlex must ensure that each algorithm requiring the use of a GPU has sole access to the GPU it is running on for the duration of the algorithm's execution.
+A third example of a limited resource could be an algorithm's declaration that it requires spawning some number of threads for it execution (rather than using the framework's task-based execution model).
+Such an algorithm could declare the need for the reservation of some number of threads by requiing that number of thread resources :need:`DUNE 152`.
+The framework would then ensure that only as many threads as the configuration has provided can be used by algoirthms at any one time.
+These resources are called *limited resources*, because the framework is responsible for limiting the access to the resource to one algorithm at a time.
 
-   Refer to :need:`DUNE 45`, :need:`DUNE 145`
 
-Explain what a limited resource is and why it is useful.
+An algorithm to be used by Phlex indicates that it requires a limited resource by requiring an argument that denotes such a resource.
 
 GPUs
 ----
 
-.. todo::
+In order to allow algorithms to make use of GPUs, and to allow the composition of workflows that involve both CPU-based and GPU-based algorithms, Phlex provides a mechanism for an algorithm that requires access to a GPU to declare that fact :need:`DUNE 54`.
+This is done by making the algorithm accept a resource that denotes the GPU.
+Phlex can support running on platforms that provide access to more than one GPU while ensuring that a given algorithm has sole access to the GPU it requires while it is executing.
+Phlex also provides, through the same mechanism, the ability for an algorithm to specify that it requires remote access to a GPU.
 
-   Refer to :need:`DUNE 54`
-
-Say what access to the GPU resource provides (perhaps sole access to the GPU hardware for the time the resource is in scope).
 
 Random Number Resource
 ----------------------
@@ -63,15 +69,9 @@ Counter-based random number generators (CBRNGs) [Wiki-CBRNG]_ each contain one i
 User-defined Resources
 ----------------------
 
-.. todo::
-
-   Refer to :need:`DUNE 149`, :need:`DUNE 152`
-
-.. code:: c++
+While Phlex will provide some commonly-used types to represent resources, it will also be possible for users to create new types to represent a new type of resouce, with no modifications to the Phlex framework code :need:`DUNE 149`.
+Such resource types have no dependency on Phlex, so that a user algorithm employing such a resource does not thereby incur any dependency on the framework.
 
-   PHLEX_REGISTER_RESOURCE(config)
-   {
-   }
 
 .. only:: html