From 15a32deba37aed96e51323cfa699956f1e4b45f5 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 4 Oct 2022 13:04:13 -0400 Subject: [PATCH 1/4] Small clarification to buffer sync rules The section on buffer synchronization rules define the scenarios when the buffer destructor must block vs. the scenarios where it does not block. The old wording made it seem like a buffer created from no host pointer is only non-blocking if it uses the default memory allocator. I assume this was not our intent, and such a buffer should have a non-blocking destructor regardless of the memory allocator. The main change in this PR is to remove the phrase "and using the default buffer allocator". However, I also reworded a bit to clarify which type of buffers we are talking about. --- adoc/chapters/programming_interface.adoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 0b4a3ef7d..205127f4e 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -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 + 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. + -- When the buffer is destroyed, the destructor will block until all From 87a71b125e396b8f55a349ee0ddae53f902eed11 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Wed, 12 Oct 2022 15:35:19 -0400 Subject: [PATCH 2/4] Addess review comment, clarify wording Avoid the word "mapped" and say "used to construct" instead. --- adoc/chapters/programming_interface.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 205127f4e..6ce710fc4 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -4986,10 +4986,10 @@ More precisely: . 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 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. + memory is modified by the host or if it is used to construct 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. + -- When the buffer is destroyed, the destructor will block until all From f4f70c77f0b238d42b9b339cfd1c60a1b4f2b8e9 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Wed, 12 Oct 2022 15:46:47 -0400 Subject: [PATCH 3/4] Clarify buffer allocator lifetime Clarify that the implementation may keep a copy of a buffer allocator even after the buffer is destroyed. --- adoc/chapters/programming_interface.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 6ce710fc4..774cc3713 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -4162,6 +4162,19 @@ host. Note that in this case the runtime will raise an error if it requires host memory but it is not available (e.g when moving data across <> contexts). +In some cases, the implementation may retain a copy of the allocator object +even after the buffer is destroyed. For example, this can happen when the +buffer object is destroyed before commands using accessors to the buffer have +completed. Therefore, the application must be prepared for calls to the +allocator even after the buffer is destroyed. + +[NOTE] +==== +If the application needs to know when the implementation has destroyed all +copies of the allocator, it can maintain a reference count within the +allocator. +==== + The definition of allocators extends the current functionality of SYCL, ensuring that users can define allocator functions for specific hardware or certain complex shared memory mechanisms (e.g. NUMA), and improves From 4b8b67d31420b868398128ecc162e9cef7cb3cdf Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 13 Oct 2022 12:02:21 -0400 Subject: [PATCH 4/4] Small change in wording Co-authored-by: Ronan Keryell --- adoc/chapters/programming_interface.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 774cc3713..f00489061 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -4999,7 +4999,7 @@ More precisely: . 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 host memory are unspecified for the lifetime of the buffer. If the host - memory is modified by the host or if it is used to construct another + memory is modified on the host or if it is used to construct 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.