[SYCL][DOC] Spec for discard queue events

sycl/doc/extensions/Avoid_event_creation/avoid_event_creation.asciidoc

@@ -0,0 +1,144 @@
+= Avoid event creation
+
+:source-highlighter: coderay
+:coderay-linenums-mode: table
+
+// This section needs to be after the document title.
+:doctype: book
+:toc2:
+:toc: left
+:encoding: utf-8
+:lang: en
+
+:blank: pass:[ +]
+
+// Set the default source code type in this document to C++,
+// for syntax highlighting purposes.  This is needed because
+// docbook uses c++ and html5 uses cpp.
+:language: {basebackend@docbook:c++:cpp}
+
+// This is necessary for asciidoc, but not for asciidoctor
+:cpp: C++
+
+== Notice
+
+IMPORTANT: This specification is a draft.
+
+Copyright (c) 2021 Intel Corporation. All rights reserved.
+
+NOTE: Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are
+trademarks of The Khronos Group Inc.  OpenCL(TM) is a trademark of Apple Inc.
+used by permission by Khronos.
+
+NOTE: This document is better viewed when rendered as html with asciidoctor.
+GitHub does not render image icons.
+
+== Dependencies
+
+This extension is written against the SYCL 2020 specification, Revision 3.
+
+== Status
+
+Working Draft
+
+This is a preview extension specification, intended to provide early access to
+a feature for review and community feedback. When the feature matures, this
+specification may be released as a formal extension.
+
+Because the interfaces defined by this specification are not final and are
+subject to change they are not intended to be used by shipping software
+products.
+
+== Introduction
+
+This extension adds `avoid_event_creation` property for `sycl::queue`, by using this property
+the application informs SYCL RT library that it doesn't care about the returned event,
+i.e the application doesn't use the returned event and just ignores it.
+
+In that case, the RT library makes a decision about internal optimization - voiding
+the creation of low-level event from the backend. The property affects only kernel cases,
+i.e. avoid creating low-level event for submission of kernels.
+Performance improvement is the main motivation for using this property.
+
+Below is a usage example:
+
+[source,c++]
+----
+  // in order queue is required for avoid_event_creation
+  sycl::queue Queue( {property::queue::in_order{}, property::queue::avoid_event_creation{}} );
+
+  // some USM preparations ..
+
+  // creating "null" events
+  sycl::event e1, e2, e3;
+
+  // returning "null" events from each submission function:
+  e1 = Queue.parallel_for(NDRange, [=](nd_item<1> item){ do_smth1(); });
+
+  e2 = Queue.single_task([=](){ do_smth2(); });
+
+  e3 = Queue.submit([&](handler &CGH) { CGH.parallel_for(NDRange, [=](nd_item<1> item){ do_smth3(); }); });
+
+  Queue.wait();
+----
+
+In the example above, the application doesn't use sycl events: `e1`, `e2`, `e3`
+and is waiting for the end of work by `queue::wait()`. The returned events will be
+`null events` - means that low-level events from backend are not created for them.
+`null event` is the event created by the default event constructor, i.e `null event`
+has the same behavior as if the event was created by the default constructor.
+
+== Limitations
+
+If the queue has this property and for some reason an event needs to be created,
+then an exception with the `errc::invalid_operation` error code will be thrown.
+
+The reasons for throwing the exception:
+
+- using streams, buffer/image accessors (excluding local accessors)
+- using together with `enable_profiling` property
+- using OOO queue
+- using https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/Assert/SYCL_ONEAPI_ASSERT.asciidoc[fallback assert feature]
+
+
+*Using this extension is well suited for kernels that use USM only, since sycl accessors are used to build a dependency graph, in which case low-level events are needed.
+
+== Version
+
+Built On: {docdate} +
+Revision: 1
+
+== Issues
+
+None.
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2021-11-09|Alexander Flegontov |*Initial public working draft*
+|========================================
+
+//************************************************************************
+//Other formatting suggestions:
+//
+//* Use *bold* text for host APIs, or [source] syntax highlighting.
+//* Use +mono+ text for device APIs, or [source] syntax highlighting.
+//* Use +mono+ text for extension names, types, or enum values.
+//* Use _italics_ for parameters.
+//************************************************************************
+© 2021 GitHub, Inc.
+Terms
+Privacy
+Security
+Status
+Docs
+Contact GitHub
+Pricing
+API
+Training
+Blog
+About

sycl/doc/extensions/README.md

@@ -49,6 +49,7 @@ DPC++ extensions status:
 | [SYCL_INTEL_bf16_conversion](Bf16Conversion/SYCL_INTEL_bf16_conversion.asciidoc)                                            | Partially supported (Level Zero: GPU)     | Currently available only on Xe HP GPU. ext_intel_bf16_conversion aspect is not supported. |
 | [Property List](PropertyList/SYCL_EXT_ONEAPI_property_list.asciidoc)                                                        | Proposal                                  | |
 | [KernelProperties](KernelProperties/KernelProperties.asciidoc)                                                              | Proposal                                  | |
+| [Avoid_event_creation](Avoid_event_creation/avoid_event_creation.asciidoc) | Proposal | |
 
 Legend: