Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Small clarification to buffer sync rules #291

Merged
merged 4 commits into from
Oct 13, 2022
Merged

Small clarification to buffer sync rules #291

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
15a32de
Small clarification to buffer sync rules
gmlueck Oct 4, 2022
87a71b1
Addess review comment, clarify wording
gmlueck Oct 12, 2022
f4f70c7
Clarify buffer allocator lifetime
gmlueck Oct 12, 2022
4b8b67d
Small change in wording
gmlueck Oct 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions adoc/chapters/programming_interface.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4976,20 +4976,20 @@ with attached host memory and is still in use.

More precisely:

. A buffer can be constructed with just a size and using the default
buffer allocator. The memory management for this type of buffer is
entirely handled by the SYCL system. The destructor for this type of
. A buffer can be constructed from a [code]#range# (and without a
[code]#hostData# pointer). The memory management for this type of buffer
is entirely handled by the SYCL system. The destructor for this type of
buffer does not need to block, even if work on the buffer has not
completed. Instead, the SYCL system frees any storage required for the
buffer asynchronously when it is no longer in use in queues. The initial
contents of the buffer are unspecified.
. A buffer can be constructed with associated host memory and a default
buffer allocator. The buffer will use this host memory for its full
lifetime, but the contents of this host memory are unspecified for the
lifetime of the buffer. If the host memory is modified by the host, or
mapped to another buffer or image during the lifetime of this buffer,
then the results are undefined. The initial contents of the buffer will
be the contents of the host memory at the time of construction.
. A buffer can be constructed from a [code]#hostData# pointer. The buffer
will use this host memory for its full lifetime, but the contents of this
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just curious about plural of contents. In French I would use singular, so just checking. :-)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is complicated in English! We use "content" for things that are uncountable and "contents" for things that are countable. It's not entirely clear whether it should be "content of memory" or "contents of memory". When I do a Google search of each, I see there are about the same number of occurrences of each. It seems like the SYCL spec use "contents of memory" in many places, so I think we should use that consistently here.

host memory are unspecified for the lifetime of the buffer. If the host
memory is modified by the host, or mapped to another buffer or image during
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not related to this PR but I have the feeling that this mapped concept is outside of the scope of SYCL since it is either an OS concept or more probable here an OpenCL SYCL 1.2.1 from the past.
At the end, mapped is kind of modifying the memory, at least making it unavailable.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that statement is just saying that you cannot construct another buffer from the same hostData pointer. I agree that the word "mapped" is a bit confusing, though.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I clarified the wording here in 87a71b1

the lifetime of this buffer, then the results are undefined. The initial
contents of the buffer will be the contents of the host memory at the time
of construction.
+
--
When the buffer is destroyed, the destructor will block until all
Expand Down