Data access chapter design

[PetroBondar]

We want to propose a new structure for the "Data access" chapter with updated content.

Currently the Reference guide "Data access" part looks like this:

In the Specification all information for this chapter is provided in section 4.7 and sycl::private_memory in 4.9.4.2.3.

We want to propose this structure of sections:

• Buffers
• Host allocation
  • +Host memory sharing
• Accessors
  • General accessor concept (4.7.6 - 4.7.6.8)
  • sycl::accessor (4.7.6.9 - 4.7.6, 4.7.6.12)
  • sycl::host_accessor (4.7.6.10, 4.7.6.12)
  • sycl::local_accessor (4.7.6.11, 4.7.6.12)
  • Unsampled image accessors (4.7.6.13)
  • Sampled image accessors (4.7.6.14)
• Synchronization primitives
• Address space classes (Multi-pointer class and explicit pointer aliases)
• Private memory (sycl::private_memory)
• Images
• Image Samplers

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

[mkinsner]

I would propose:

1. Move "Images" until second last, immediately before "Image Samplers"
2. Include "host sharing" within the "host allocation" section

[PetroBondar]

Thanks! I updated the structure according to the comment.

[tomdeakin]

Looks good to me.
I wonder if we need a subsection under buffers that calls out buffer destructor synchronisation, as it's a particularly confusing part of the spec.

[PetroBondar]

We considered adding it as a subsection into the "Buffers" so it will be visible in the page contents.
Something like this (this is from the USM Basic concept page):

Do you recommend not adding it?

[tomdeakin]

I'm recommended we do add it!

[PetroBondar]

Okay, thanks. We'll try to add it to the "Buffers". I believe we don't need an additional file for it. We will include it as a subsection inside the "Buffers" file, what do you think about this approach?

[PetroBondar]

I created a draft for this chapter in this PR: #91.

[imvucic]

@mkinsner @gmlueck
The accessor, host_accessor, and local_accessor classes have many member types and member functions with the same name and meaning. Table 79 describes these common types and Table 80 describes the common member functions.

We have several possibility, please check below or propose new approach :

1. Duplicate tables in accessor, host_accessor, and local_accessor sub-chapters
2. Only keep links(79/80) to Specification tables
3. Create one new sub-section(Common members for buffer and local accessors) and point out on that link from different chapters

BR,
Marko

[tomdeakin]

WG suggests Option 1 please!

[imvucic]

The common member types and functions incorporated with commit: abbdc14
Will be duplicated in host_accessor, and local_accessor based on WG suggestion.