diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_status_query.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_status_query.asciidoc new file mode 100644 index 0000000000000..44564fa21238f --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_status_query.asciidoc @@ -0,0 +1,145 @@ += sycl_ext_oneapi_queue_status_query + +: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 +:dpcpp: pass:[DPC++] + +// 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} + + +== Notice + +Copyright (C) 2022-2022 Intel Corporation. All rights reserved. + +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. + + +== Contact + +To report problems with this extension, please open a new issue at: + +https://github.com/intel/llvm/issues + + +== Dependencies + +This extension is written against the SYCL 2020 revision 4 specification. All +references below to the "core SYCL specification" or to section numbers in the +SYCL specification refer to that revision. + +== Status + +This is a proposed extension specification, intended to gather community +feedback. Interfaces defined in this specification may not be implemented yet +or may be in a preliminary state. The specification itself may also change in +incompatible ways before it is finalized. *Shipping software products should +not rely on APIs defined in this specification.* + +== Overview + +CUDA has a stream API +(link:https://docs.nvidia.com/cuda/cuda-runtime-api/group__CUDART__STREAM.html#group__CUDART__STREAM_1g2021adeb17905c7ec2a3c1bf125c5435[CudaStreamQuery]) which checks if all operations in a CUDA stream have been completed. Such a feature is lacking in `sycl::queue`. This extension adds a new query API to introspect queues. In particular, `ext_oneapi_empty` can be used to replace the `CudaStreamQuery`. This should ease the porting applications from CUDA to SYCL. + +== Specification + +=== Feature test macro + + +This extension provides a feature-test macro as described in the core SYCL +specification. An implementation supporting this extension must predefine the +macro `SYCL_EXT_ONEAPI_QUEUE_STATUS_QUERY` to one of the values defined in the table +below. Applications can test for the existence of this macro to determine if +the implementation supports this feature, or applications can test the macro's +value to determine which of the extension's features the implementation +supports. + +[%header,cols="2,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + + +=== Signatures and Semantics + +This extension adds the following new member functions to the SYCL `queue` class. + +[source,c++] +---- +namespace sycl { + +class queue { + bool ext_oneapi_empty() const; + size_t ext_oneapi_size() const; + std::vector ext_oneapi_get_wait_list() const; +}; + +} // namespace sycl +---- + + +The semantics of the new functions are: + +[frame="topbot",options="header"] +|=== +|Function |Description + +// --- ROW BREAK --- +a| +[source,c++] +---- +bool ext_oneapi_empty() const +---- +| +Returns `true` if `ext_oneapi_size() == 0`. + +// --- ROW BREAK --- +a| +[source,c++] +---- +size_t ext_oneapi_size() const +---- +| +Returns the number of enqueued `commands` in the queue that have not been +completed. Since the implementation completes commands from the queue +asynchronously, the returned value is a snapshot in time, and the actual +number of uncompleted commands may be different by the time the function +returns. Note that the behavior of `ext_oneapi_size()` is associated with the SYCL +`queue` and not with the underlying native-backend-object. + +// --- ROW BREAK --- +a| +[source,c++] +---- +std::vector ext_oneapi_get_wait_list() const +---- +| +Returns the list of events such that waiting for all returned events +guarantees that all enqueued commands in the queue have been completed. +Implementations are free to omit events that don't contribute +to the semantic of `ext_oneapi_get_wait_list()`. For example, +whether already completed events or non-leaf events of the dependency sub-graph +managed by the queue are included in the returned list is implementation-defined. +This implies that the number of events returned by `ext_oneapi_get_wait_list()` +maybe different from the value returned by `ext_oneapi_size()`. +a| +|=== + +== Similar Work + +- `ext_oneapi_get_wait_list` is inspired by the hipSYCL extension link:https://github.com/illuhad/hipSYCL/blob/develop/doc/extensions.md#hipsycl_ext_queue_wait_list[queue_wait_list].