More documentation improvements #1835
Conversation
akukanov
requested review from
timmiesmith,
rarutyun,
dcbenito,
danhoeflinger and
MikeDvorskiy
documentation/library_guide/parallel_api/execution_policies.rst
Outdated
Show resolved
Hide resolved
akukanov
force-pushed
the
dev/doc-policy-improvements-akukanov
branch
from
d40104a to
9457aa0
Compare
documentation/library_guide/parallel_api/pass_data_algorithms.rst
Outdated
Show resolved
Hide resolved
documentation/library_guide/parallel_api/pass_data_algorithms.rst
Outdated
Show resolved
Hide resolved
| also referred to as *standard aligned* or *host execution policies*, and the *device execution policies* | ||
| to run data parallel computations on heterogeneous systems. |
There was a problem hiding this comment.
It may be more clear if we make this into two sentences. Change the comma to a period then start the next sentence as "|onedpl_short| also provides the device execution policies ..."
There was a problem hiding this comment.
OK, I will think of it - but perhaps in another patch, unless bigger changes are requested for this one.
There was a problem hiding this comment.
not required, the rest LGTM. About to approve.
There was a problem hiding this comment.
Changed "and ..." to "as well as device execution policies", but otherwise left it as is. I do not want to split, as the "According to the spec" part applies to both policy kinds.
| in the ``oneapi/dpl/execution`` header. The policies have the following meaning: | ||
|
|
||
| ====================== ===================================================== | ||
| Policy Value or Type Description |
There was a problem hiding this comment.
Probably, does it make sense to "split" (to have two tables) for the host policies
(policy values only) and for device policy types and policy values?
Otherwise, the column "Policy Value or Type" might confuse a user.
There was a problem hiding this comment.
Thanks.
The description indicates what is type and what is a value. I can also add "type" to the types :)
There was a problem hiding this comment.
Tried a few variations, and ended up with changing the column heading to "Policy Name / Type".
| icpx -fsycl -fsycl-pstl-offload=gpu program.cpp -o program | ||
|
|
||
| This option redirects C++ parallel algorithms invoked with the ``std::execution::par_unseq`` policy | ||
| to |onedpl_short| algorithms. It does not change the behavior of the |onedpl_short| execution policies and algorithms |
There was a problem hiding this comment.
While I understand (after several reading) that onedpl_short is related to both execution policies and algorithms, perhaps adding it explicitly for the second time helps make this sentence clearer Maybe adding "themselves" also could help. I mean something like:
| to |onedpl_short| algorithms. It does not change the behavior of the |onedpl_short| execution policies and algorithms | |
| to |onedpl_short| algorithms. It does not change the behavior of the |onedpl_short| execution policies and |onedpl_short| algorithms themselves |
There was a problem hiding this comment.
"... that are directly used in the code" below should convey similar meaning. Anyway, I will think how to make it clearer.
There was a problem hiding this comment.
Resolved by swapping the words: "It does not change the behavior of the |onedpl_short| algorithms and
execution policies that are directly used in the code."
| namespace, to a parallel algorithm. | ||
| #. Use the C++ standard execution policies: | ||
| #. Pass a |onedpl_short| execution policy object as the first argument to a parallel algorithm | ||
| to specify the desired execution behavior. |
There was a problem hiding this comment.
"desired execution behavior" - I remembered that a host execution policy doesn't guarantee execution behavior, it may have the desired behavior, it is just a hint.
A device policy provides the desired (device execution) execution behavior.
Probably this difference should be explained in the doc.
There was a problem hiding this comment.
Thanks, I will think of it.
There was a problem hiding this comment.
I rephrased it as "to indicate the desired behavior" to sound a bit less formal. Anyway, the sentence describes a user action, and the behavior is desired, not guaranteed. Also I added "possible" to execution descriptions for unseq and par.
|
The new feedback will be addressed in another patch. |
* Align terminology and improve wording related to execution policies * Add information about -fsycl-pstl-offload and improve the known issue note * Add the limitation on the use of pointer-to-member objects * Clarify the need for policies and data storage to match * Formatting and stylistic improvements
* Align terminology and improve wording related to execution policies * Add information about -fsycl-pstl-offload and improve the known issue note * Add the limitation on the use of pointer-to-member objects * Clarify the need for policies and data storage to match * Formatting and stylistic improvements
This patch proposes
-fscyl-pstl-offload;par_unseq,paretc.;as well as formatting and other improvements.