From c09c7a761a830be2264527478013519e98d9e8a9 Mon Sep 17 00:00:00 2001 From: Duncan McBain Date: Tue, 27 Aug 2019 16:41:57 +0100 Subject: [PATCH 1/4] Add proposal for default-constructible buffers Default constructible buffers would be a useful addition for generic code. This proposal adds a zero-argument constructor and functions for determining whether or not a buffer is usable. --- .../default-constructed-buffers.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 default-constructed-buffers/default-constructed-buffers.md diff --git a/default-constructed-buffers/default-constructed-buffers.md b/default-constructed-buffers/default-constructed-buffers.md new file mode 100644 index 0000000..9a83e45 --- /dev/null +++ b/default-constructed-buffers/default-constructed-buffers.md @@ -0,0 +1,88 @@ +# Default-constructed Buffers + +Proposal ID | TBC +---------------- | --------------------------- +Name | Default-constructed Buffers +Date of Creation | 2019-08-20 +Target | +Status | WIP +Author | Duncan McBain [Duncan McBain](mailto:duncan@codeplay.com) +Contributors | + +## Description + +In SYCL, there are no buffer constructors that take no arguments, which means +that `cl::sycl::buffer` cannot be default-constructed. However, this limits the +use of buffers in some interfaces. Consider a library function that has an +optional user-provided allocation for temporary data. The library can avoid +allocations if the library user so desires by providing a buffer here, but how +should the user indicate that allocation is allowed? A natural way would be to +provide a default argument in the API function: + +```c++ +template +void foo(Allocation_t input_a, + Allocation_t input_b, + Allocation_t temp = Allocation_t{}); +``` + +For `Allocation_t` types that are pointer-like, the library can check for +`nullptr` and allocate if this condition is true. A similar mechanism that +allows `cl::sycl::buffer` to be constructed and checked for usability would +aid their use in this style of generic interface. + +## Proposal + +The `cl::sycl::buffer` class should be augmented with an additional constructor +that takes no arguments, which initialises the buffer with a zero-size range. +```c++ +namespace cl { +namespace sycl { +template +class buffer { + buffer(); + + bool is_valid() const noexcept; + + explicit operator bool() const noexcept; +}; +} // namespace sycl +} // namespace cl +``` +The template arguments should remain the same, so that the argument can be +rebound to a new `buffer` instance later using the copy constructor. + +The `is_valid()` call would allow the programmer to query whether or not +the buffer can be used, i.e. whether or not it was constructed with a range of +size zero. The operator would call this same function but allow its use in +if statements. + +## Sample code + +```c++ +#include +using namespace sycl = cl::sycl; +using namespace access = sycl::access; + +class name; + +void api_func(sycl::queue& q, + sycl::buffer input, sycl::buffer output, + sycl::buffer workspace = sycl::buffer{}) { + if (!workspace) { + // calculate required size for workspace + constexper auto size = 2048llu; + workspace = sycl::buffer{sycl::range<1>{size}}; + } + // use buffer + q.submit([&] (sycl::handler& cgh) { + auto acc_in = input.get_access(cgh); + auto acc_out = input.get_access(cgh); + auto acc_workspace = input.get_access(cgh); + cgh.single_task([=]() { + // uses accessors + }); + }); +} +``` From 25e98b18cb7bd3b229ad006c32068a6f2f5d3136 Mon Sep 17 00:00:00 2001 From: Duncan McBain Date: Thu, 5 Sep 2019 18:48:33 +0100 Subject: [PATCH 2/4] Update with review feedback * Add hopefully nonconflicting proposal number * Clarify what it means to use a default buffer and its functions... * ...and therefore add Gordon as a contributor :) * Add suggested operator clarification --- README.md | 1 + .../default-constructed-buffers.md | 18 +++++++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b2a1dc8..7f3e12f 100644 --- a/README.md +++ b/README.md @@ -57,3 +57,4 @@ Each proposal in the table below will be tagged with one of the following states | CP017 | [Host Access](host_access/index.md) | SYCL 1.2.1 vendor extension | 17 September 2018 | 13 December 2018 | _Available since CE 1.0.3_ | | CP018 | [Built-in kernels](builtin_kernels/index.md) | SYCL 1.2.1 vendor extension | 12 October 2018 | 12 October 2018 | _Available since CE 1.0.3_ | | CP019 | [On-chip Memory Allocation](onchip-memory/index.md) | SYCL 1.2.1 vendor extension | 03 December 2018 | 03 December 2018 | _Available since CE 1.0.3_ | +| CP020 | [Default-Constructed Buffers](default-constructed-buffers/default-constructed-buffers.md) | SYCL 1.2.1 | 27 August 2019 | 5 September 2019 | _Draft_ | diff --git a/default-constructed-buffers/default-constructed-buffers.md b/default-constructed-buffers/default-constructed-buffers.md index 9a83e45..0b7a0c5 100644 --- a/default-constructed-buffers/default-constructed-buffers.md +++ b/default-constructed-buffers/default-constructed-buffers.md @@ -4,10 +4,10 @@ Proposal ID | TBC ---------------- | --------------------------- Name | Default-constructed Buffers Date of Creation | 2019-08-20 -Target | -Status | WIP +Target | SYCL 1.2.1 +Status | _Draft_ Author | Duncan McBain [Duncan McBain](mailto:duncan@codeplay.com) -Contributors | +Contributors | Duncan McBain, [Gordon Brown](mailto:gordon@codeplay.com) ## Description @@ -55,8 +55,16 @@ rebound to a new `buffer` instance later using the copy constructor. The `is_valid()` call would allow the programmer to query whether or not the buffer can be used, i.e. whether or not it was constructed with a range of -size zero. The operator would call this same function but allow its use in -if statements. +size zero. The explicit conversion operator would call this same function but +allow its use in `if` statements. + +Requesting access from a default-constructed buffer should throw an exception. +It is not meaningful to use a zero-sized allocation on-device. Since there is +no allocation associated with the `buffer`, `cl::sycl::buffer::set_final_data` +and `cl::sycl::buffer::set_write_back` should behave as if the `buffer` had a +final pointer of `nullptr` at all times. The other functions in the `buffer` +API should behave as though the buffer were constructed with a `range` of size +zero and otherwise behave normally. ## Sample code From f04ef4de3ec47174cab5b3a2087d5021d175ddc1 Mon Sep 17 00:00:00 2001 From: Ruyman Date: Sun, 22 Sep 2019 11:12:39 -0500 Subject: [PATCH 3/4] Assigned CP021 extension ID --- default-constructed-buffers/default-constructed-buffers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/default-constructed-buffers/default-constructed-buffers.md b/default-constructed-buffers/default-constructed-buffers.md index 0b7a0c5..073ee9d 100644 --- a/default-constructed-buffers/default-constructed-buffers.md +++ b/default-constructed-buffers/default-constructed-buffers.md @@ -1,6 +1,6 @@ # Default-constructed Buffers -Proposal ID | TBC +Proposal ID | CP021 ---------------- | --------------------------- Name | Default-constructed Buffers Date of Creation | 2019-08-20 From 03f2831fe717f08b2872a971ddd74756e66e702f Mon Sep 17 00:00:00 2001 From: Ruyman Reyes Date: Sun, 22 Sep 2019 11:27:28 -0500 Subject: [PATCH 4/4] Added extension ID in Readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7f3e12f..ad2f500 100644 --- a/README.md +++ b/README.md @@ -57,4 +57,4 @@ Each proposal in the table below will be tagged with one of the following states | CP017 | [Host Access](host_access/index.md) | SYCL 1.2.1 vendor extension | 17 September 2018 | 13 December 2018 | _Available since CE 1.0.3_ | | CP018 | [Built-in kernels](builtin_kernels/index.md) | SYCL 1.2.1 vendor extension | 12 October 2018 | 12 October 2018 | _Available since CE 1.0.3_ | | CP019 | [On-chip Memory Allocation](onchip-memory/index.md) | SYCL 1.2.1 vendor extension | 03 December 2018 | 03 December 2018 | _Available since CE 1.0.3_ | -| CP020 | [Default-Constructed Buffers](default-constructed-buffers/default-constructed-buffers.md) | SYCL 1.2.1 | 27 August 2019 | 5 September 2019 | _Draft_ | +| CP021 | [Default-Constructed Buffers](default-constructed-buffers/default-constructed-buffers.md) | SYCL 1.2.1 | 27 August 2019 | 5 September 2019 | _Draft_ |