From e8f1f29b584ed0e4f899c31dcabb645dc3bda719 Mon Sep 17 00:00:00 2001 From: jbrodman Date: Fri, 14 Feb 2020 05:27:18 -0500 Subject: [PATCH] [SYCL][DOC][Ordered Queue] Remove old proposal and make note of deprecation (#1131) Signed-off-by: James Brodman --- .../extensions/OrderedQueue/OrderedQueue.adoc | 18 ----- .../OrderedQueue/OrderedQueue_v2.adoc | 2 + .../extensions/OrderedQueue/ordered_queue.h | 73 ------------------- 3 files changed, 2 insertions(+), 91 deletions(-) delete mode 100644 sycl/doc/extensions/OrderedQueue/OrderedQueue.adoc delete mode 100644 sycl/doc/extensions/OrderedQueue/ordered_queue.h diff --git a/sycl/doc/extensions/OrderedQueue/OrderedQueue.adoc b/sycl/doc/extensions/OrderedQueue/OrderedQueue.adoc deleted file mode 100644 index 04d2015d9afb3..0000000000000 --- a/sycl/doc/extensions/OrderedQueue/OrderedQueue.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= SYCL Proposals: Ordered Queue -James Brodman -v0.1 -:source-highlighter: pygments -:icons: font -== Introduction -This document presents an addition proposed for a future version of the SYCL Specification. The goal of this proposal is to reduce the complexity and verbosity of using SYCL for programmers. - -== Ordered Queue -Queues in SYCL are out-of-order by default. SYCL constructs directed acyclic graphs to ensure tasks are properly ordered based on their data dependences. However, many programs only require linear DAGs. The overheads of constructing and managing DAGs are unnecessary for this class of program. The `ordered_queue` class exists to serve this class of programs by providing simple in-order semantics. `ordered_queue` otherwise functions identically to the normal SYCL `queue`. Due to the simpler semantics and task dependences of an in-order queue, additional programming simplifications are also possible. -[source,cpp] ----- -include::ordered_queue.h[] ----- - -=== API Simplifications -Since `ordered_queue` has simpler in-order semantics, programmers do not need to specify dependences between tasks by building DAGs based on data dependences. Command group scope for tasks submitted to `ordered_queue` only needs to contain kernel definitions or explicit memory operations in order to define valid execution. Consequently, the `single_task` and `parallel_for` APIs, normally used on the command group `handler` class, are available directly on the `ordered_queue` class. - diff --git a/sycl/doc/extensions/OrderedQueue/OrderedQueue_v2.adoc b/sycl/doc/extensions/OrderedQueue/OrderedQueue_v2.adoc index 73c6b10826cbe..0b66b2ac17da1 100644 --- a/sycl/doc/extensions/OrderedQueue/OrderedQueue_v2.adoc +++ b/sycl/doc/extensions/OrderedQueue/OrderedQueue_v2.adoc @@ -6,6 +6,8 @@ v0.2 == Introduction This document presents an addition proposed for a future version of the SYCL Specification. The goal of this proposal is to reduce the complexity and verbosity of using SYCL for programmers. +NOTE: This proposal replaces the previous one that was based on a separate class for in-order queues. + == Queue Order Properties Queues in SYCL are out-of-order by default. SYCL constructs directed acyclic graphs to ensure tasks are properly ordered based on their data dependences. However, many programs only require linear DAGs. The overheads of constructing and managing DAGs are unnecessary for this class of program. The `in_order` queue property is proposed to serve this class of programs by providing programmer-specified in-order semantics. This property is used with the existing `property_list` mechanism that is part of the normal SYCL `queue`. diff --git a/sycl/doc/extensions/OrderedQueue/ordered_queue.h b/sycl/doc/extensions/OrderedQueue/ordered_queue.h deleted file mode 100644 index e4a3ed5050a6b..0000000000000 --- a/sycl/doc/extensions/OrderedQueue/ordered_queue.h +++ /dev/null @@ -1,73 +0,0 @@ -namespace sycl { -class ordered_queue { - public: - explicit ordered_queue(const property_list &propList = {}); - - ordered_queue(const async_handler &asyncHandler, - const property_list &propList = {}); - - ordered_queue(const device_selector &deviceSelector, - const property_list &propList = {}); - - ordered_queue(const device_selector &deviceSelector, - const async_handler &asyncHandler, const property_list &propList = {}); - - ordered_queue(const device &syclDevice, const property_list &propList = {}); - - ordered_queue(const device &syclDevice, const async_handler &asyncHandler, - const property_list &propList = {}); - - ordered_queue(const context &syclContext, const device_selector &deviceSelector, - const property_list &propList = {}); - - ordered_queue(const context &syclContext, const device_selector &deviceSelector, - const async_handler &asyncHandler, const property_list &propList = {}); - - ordered_queue(cl_command_queue clQueue, const context& syclContext, - const async_handler &asyncHandler = {}); - - /* -- common interface members -- */ - - /* -- property interface members -- */ - - cl_command_queue get() const; - - context get_context() const; - - device get_device() const; - - bool is_host() const; - - template - typename info::param_traits::return_type get_info() const; - - template - event submit(T cgf); - - template - event submit(T cgf, const queue &secondaryQueue); - - void wait(); - - void wait_and_throw(); - - void throw_asynchronous(); - - /* -- API simplifications -- */ - - template - event single_task(KernelType kernelFunc); - - template - event parallel_for(range numWorkItems, kernelType kernelFunc); - - template - event parallel_for(range numWorkItems, - id workItemOffset, kernelType kernelFunc); - - template - event parallel_for(nd_range executionRange, kernelType kernelFunc); - -}; -} // namespace sycl -