Simplify the introduction #694
Conversation
The changes in this commit aim to simplify the introduction, by: - Simplifying complex sentences; - Removing (most) statements that do not apply to all implementations; - Consolidating references to C++, OpenCL, etc to avoid repetition; and - Highlighting the key features of SYCL with shorter bullet points. The result is a significantly shorter introduction (300 words vs 1200 words) that succinctly summarizes what SYCL is and why developers should use it.
|
I think this is a very nice simplification. It is clear and to the point. |
|
Quick review on this please. |
Co-authored-by: Tom Deakin <[email protected]>
|
You mean the one that says "or ``backend''"? I already linked the second one to the feature.
Right, they'll be ignored. Those comments were mostly for me to refer to when drafting the new introduction, but I left them in thinking they might help to guide where to place new updates to the introduction in future. |
|
Looking at the list of commented reader questions, would it make sense to have 1-3 sentences somewhere in there on "What is SYCL used for?"? Obviously it's not a topic for a spec, but it might make sense in an introduction. What I have in mind is saying things like, "High-performance libraries are developed on top of SYCL, and some applications use SYCL directly. SYCL is used in physics, chemistry, AI, and other domains. SYCL runs on anything from a laptop to a supercomputer." (But worded better.) Either way, it's a great rewrite of the intro. |
Co-authored-by: Erik Tomusk <[email protected]>
| source files as normal {cpp} code, alongside any code intended to be run on a | ||
| system's host processor. | ||
| This concept, known as "`single-source`" programming, reduces the complexity of | ||
| heterogeneous programming for developers and gives compilers greater |
There was a problem hiding this comment.
+ increase type-safety across the host-device boundary?
There was a problem hiding this comment.
I'm having trouble working this in without making the sentence very complicated. I can't see a way to mention type safety specifically without converting things into a list:
This concept--known as "single-source programming"--has several advantages: it reduces the complexity of heterogeneous programming for developers; it guarantees type-safety across the host-device boundary; and it gives compilers greater opportunities to optimize across the host-device boundary.
I've made a minor change in deb636e which I hope gets across the intent without being so complicated:
This concept, known as "
single-source" programming, reduces the complexity of heterogeneous programming for developers and gives compilers greater opportunities to analyze/optimize across the host-device boundary.
This acknowledges that the advantages extend beyond optimization to analysis, but doesn't go as far as mentioning type safety.
There was a problem hiding this comment.
@keryell to add something in another PR about this.
| simple way to build task-graphs without manually managing dependencies. | ||
|
|
||
| * <<sec:usm, Unified Shared Memory>> (USM) provides an explicit, | ||
| pointer-based, mechanism for managing and sharing data. |
There was a problem hiding this comment.
It becomes urgent to come with an extension providing a safer API for this. 😿
There was a problem hiding this comment.
Are you suggesting that we add a comment about safety here?
There was a problem hiding this comment.
Are you suggesting that we add a comment about safety here?
No. But it is sad that we go along to #703
|
WG approved to merge. |
|
Also as clarification to 2020 |
Cherry pick KhronosGroup#694 from main (cherry picked from commit f99eca5)
The changes in this commit aim to simplify the introduction, by:
The result is a significantly shorter introduction (300 words vs 1200 words) that succinctly summarizes what SYCL is and why developers should use it.
Some of the changes I've made here might be a little bit contentious, so I want to provide a little more insight into how I decided what to cut and what to keep.
First, I wrote out a list of questions that I think a reader would hope to be able to answer by reading the introduction. (You can see these questions as comments in the AsciiDoc). Then I reordered all the paragraphs in the existing introduction under those headings, and it became apparent that there was quite a lot of repetition around alignment with C++, access to low-level OpenCL features, etc. So I tried to collapse all of that together.
Second, I took out (almost) everything that described how SYCL implementations work. I convinced myself a lot of this was outdated and probably didn't apply to most implementations. For example, there were claims that it is always possible to use SYCL with arbitrary host compilers and/or without special linkers. I made an exception for a statement that SYCL implementations could choose to be implemented on top of nothing but standard C++, because I think that highlights an interesting aspect of SYCL's design philosophy.
Third, I tried to boil everything down to the really important points, inspired by the introduction to the OpenCL specification. We've got the rest of the specification to explain how features like buffers work, and I think it makes more sense to just point interested readers to the relevant sections.