Expressing Parallelism chapter design

[PetroBondar]

After investigating Specification chapters related to Expressing parallelism we want to propose and discuss the new structure of related topics in the Reference guide.

Currently the Reference guide "Expressing parallelism" part looks like this:

In the Specification all information for this chapter is provided in sections 4.9, 4.11, 4.12.

We want to propose this structure of Sections:

• Defining kernels
• Range Classes:
  • sycl::range
  • sycl::nd_range
• sycl::id (could also relate to Item Classes or Range Classes)
• Item Classes:
  • sycl::item
  • sycl::nd_item
  • sycl::h_item
• sycl::group
• sycl::sub_group
• sycl::handler
• Specialization Constants
• Kernel bundles
• sycl::kernel
• sycl::device_image
• Reduction variables

Could you please also review this structure and comment on how we can improve it?

Also, which coverage of those topics do you expect in this part? Some of the sections, f.e. "Kernel bundles", contain a lot of information, which could be overwhelming for the Reference guide. Should we in such cases add less information and just add references to the Specs?

[mkinsner]

I would propose that "defining kernels" be first in this chapter of the reference guide. So moved to the top of the list.

Kernel bundles should be included, with sufficient subsection headings that the navigation bar makes the section possible to navigate. The subsections in the spec should be a reasonable starting point.

Host tasks probably don't belong in the expressing parallelism chapter. In the spec they're the next second level section (same level as "expressing parallelism through kernels"). Can we keep this structure?

[PetroBondar]

Thanks for the comment!

I rearranged the section sequence (placed "Defining Kernels" first), and I removed "Host tasks" from the discussion in this task. We'll create a separate chapter for it later. Now it should look better.

[tomdeakin]

I think this structure is good overall, and an improvement over the existing structure.
Where do you plan to put in hierarchical parallelism? This is currently in the spec with a note to not use it as it is likely to change, so whilst I don't think it's a priority, do you have a plan? It's relevant because sycl::h_item comes from that part of the spec.

[PetroBondar]

I think we'll still add the current state of sections related to hierarchical parallelism, but we'll add notes or mention somehow that those sections are likely to change, like it was done in Specs 3.9.5.

We'll have related topics in the Reference guide like this in the sycl::handler or the sycl::h_item.

What do you think about an approach like this?

[mkinsner]

I think we'll still add the current state of sections related to hierarchical parallelism, but we'll add notes or mention somehow that those sections are likely to change, like it was done in Specs 3.9.5.

We'll have related topics in the Reference guide like this in the sycl::handler or the sycl::h_item.

What do you think about an approach like this?

That approach makes sense, so sounds good to me.