[oneDPL] Improve clarity in buffer wrapper usage

[danhoeflinger]

Improve clarity and consistency in how we describe buffer position objects, (the return of oneapi::dpl::begin/end), and how they interact with oneDPL iterators and the indirectly device accessible trait.

This does not change anything about the semantics of the specification, but hopes to improve clarity and add some text which was previously implied.

[Copilot]

Pull Request Overview

This PR improves clarity and consistency in the oneDPL documentation by better describing buffer position objects and their relationship with oneDPL iterators and the indirectly device accessible trait.

Key changes:

• Enhanced documentation of buffer position objects and their behavior with device policies
• Added clarification on how oneDPL iterators interact with buffer position objects
• Improved terminology consistency by replacing "unspecified iterator-like type" with proper references to buffer position objects

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
source/elements/oneDPL/source/parallel_api/iterators.rst	Enhanced documentation of buffer position objects, indirectly device accessible iterators, and improved terminology consistency
source/elements/oneDPL/source/parallel_api/execution_policies.rst	Updated description to clarify that SYCL buffers are passed as buffer position objects

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[akukanov]

I think there is one point that we discussed when adding indirect device accessibility to the specification: if oneDPL special iterators are built on top of buffer wrappers, they also in a sense become buffer wrappers. That affects device accessibility, but not only - that also affects other behavior, and specifically dereferencing - either on the host or on a device. And while the oneDPL algorithms know how to deal with that, direct use of such compound iterators might be problematic.

This point is important I believe, but it is not addressed in the patch.

[danhoeflinger]

I think there is one point that we discussed when adding indirect device accessibility to the specification: if oneDPL special iterators are built on top of buffer wrappers, they also in a sense become buffer wrappers. That affects device accessibility, but not only - that also affects other behavior, and specifically dereferencing - either on the host or on a device. And while the oneDPL algorithms know how to deal with that, direct use of such compound iterators might be problematic.

This point is important I believe, but it is not addressed in the patch.

Ah, I understand now, you are correct that this is missing. I think this can probably be addressed with a section in the Iterators page describing the functionality loss when a source iterator is or is composed of a buffer wrapper (and some pointers to this section where we describe buffer wrapper objects as valid source "iterators").

I don't think it is worth much to go so far as to expose a public trait like is_buffer_wrapper, especially because to make this compatible with custom iterators, users would need to customize it similar to indirectly device accessible. However, its something we could consider.