From a62830f2f40f7119017db66a441cbf2d5565c4ea Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Sat, 20 Jul 2024 16:15:11 -0400 Subject: [PATCH 1/2] Update context description to new format Update the section describing the `context` class to the new format. --- adoc/chapters/glossary.adoc | 2 +- adoc/chapters/information_descriptors.adoc | 2 +- adoc/chapters/programming_interface.adoc | 376 ++++++++++++--------- 3 files changed, 215 insertions(+), 165 deletions(-) diff --git a/adoc/chapters/glossary.adoc b/adoc/chapters/glossary.adoc index b276e8c8..a40fbba7 100644 --- a/adoc/chapters/glossary.adoc +++ b/adoc/chapters/glossary.adoc @@ -131,7 +131,7 @@ For the full description please refer to <>. <> API to interact with a group of <> associated with a <>. The context is defined as the [code]#sycl::context# class, for further - details please see <>. + details please see <>. [[control-flow]]control flow:: When all <> in a <> are executing the same diff --git a/adoc/chapters/information_descriptors.adoc b/adoc/chapters/information_descriptors.adoc index 2cfc189a..f65eb2f0 100644 --- a/adoc/chapters/information_descriptors.adoc +++ b/adoc/chapters/information_descriptors.adoc @@ -22,7 +22,7 @@ include::{header_dir}/platformInfo.h[lines=4..-1] == Context information descriptors The following interface includes all the information descriptors for the -[code]#context# class as described in <>. +[code]#context# class. [source,,linenums] ---- include::{header_dir}/contextInfo.h[lines=4..-1] diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 41f84c6c..c9cb8c7e 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1165,263 +1165,313 @@ Returns the extensions supported by this [code]#platform#. Returns an empty list |==== - -[[sec:interface.context.class]] +[[sec:context-class]] === Context class -The <> class represents a SYCL <>. -A <> represents the runtime data structures and state required by a +The [code]#context# class represents a SYCL context. +A context represents the runtime data structures and state required by a <> API to interact with a group of devices associated with a platform. -The SYCL [code]#context# class provides the common reference semantics (see -<>). - - -==== Context interface - -The constructors and member functions of the SYCL [code]#context# class are -listed in <> and <>, -respectively. -The additional common special member functions and common member functions are -listed in <> in -<> and -<>, respectively. - -All member functions of the <> class are synchronous and errors are +All member functions of the [code]#context# class are synchronous and errors are handled by throwing synchronous SYCL exceptions. -All constructors of the SYCL <> class will construct an instance +All constructors of the [code]#context# class construct an object that is associated with a particular <>, determined by the constructor parameters or, in the case of the default constructor, the SYCL [code]#device# produced by the [code]#default_selector_v#. -A SYCL [code]#context# can optionally be constructed with an -[code]#async_handler# parameter. -In this case the [code]#async_handler# is used to report asynchronous SYCL +A context can optionally be constructed with an [code]#async_handler# parameter. +In this case the [code]#async_handler# is used to report asynchronous exceptions, as described in <>. -Information about a SYCL <> may be queried through the -[code]#get_info()# member function. +The [code]#context# class provides the common reference semantics as defined in +<>. -// Interface for class: context -[source,,linenums] +[source,role=synopsis] ---- include::{header_dir}/context.h[lines=4..-1] ---- +[[sec:context-ctors]] +==== Constructors -[[table.constructors.context]] -.Constructors of the SYCL [code]#context# class -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Constructor @ Description -a@ -[source] +.[apititle]#Default constructor# +[source,role=synopsis,id=api:context-ctor] ---- explicit context(async_handler asyncHandler = {}) ---- - a@ Constructs a SYCL [code]#context# instance using an instance of - [code]#default_selector_v# to select the associated SYCL - [code]#platform# and [code]#device(s)#. The <> that - are associated with the constructed <> are implementation-defined - but must contain the <> chosen by the device selector. The - constructed SYCL [code]#context# will use the [code]#asyncHandler# - parameter to handle exceptions. -a@ -[source] +_Effects:_ Constructs a [code]#context# object using the +[code]#default_selector_v# to determine the associated platform and devices. +The associated platform is the platform which contains the device selected by +[code]#default_selector_v#. +The <> that are associated with the constructed context are +implementation-defined but must contain the device that is selected by +[code]#default_selector_v#. +The constructed context uses the [code]#asyncHandler# parameter to handle +exceptions. + +''' + +.[apititle]#Construct from device# +[source,role=synopsis,id=api:context-ctor-dev] ---- explicit context(const device& dev, async_handler asyncHandler = {}) ---- - a@ Constructs a SYCL [code]#context# instance using the [code]#dev# parameter as the associated SYCL [code]#device# and the SYCL [code]#platform# associated with the [code]#dev# parameter as the associated SYCL [code]#platform#. The constructed SYCL [code]#context# will use the [code]#asyncHandler# parameter to handle exceptions. -a@ -[source] +_Effects:_ Constructs a [code]#context# object using the [code]#dev# parameter +to determine the associated platform and device. +The associated platform is the platform that contains [code]#dev#, and the +associated device is [code]#dev#. +The constructed context uses the [code]#asyncHandler# parameter to handle +exceptions. + +''' + +.[apititle]#Construct from device list# +[source,role=synopsis,id=api:context-ctor-dev-list] ---- explicit context(const std::vector& deviceList, async_handler asyncHandler = {}) ---- - a@ Constructs a SYCL [code]#context# instance using the SYCL [code]#device(s)# in the [code]#deviceList# parameter as the associated SYCL [code]#device(s)# and the SYCL [code]#platform# associated with each SYCL [code]#device# in the [code]#deviceList# parameter as the associated SYCL [code]#platform#. This requires that all SYCL [code]#devices# in the [code]#deviceList# parameter have the same associated SYCL [code]#platform#. The constructed SYCL [code]#context# will use the [code]#asyncHandler# parameter to handle exceptions. -|==== +_Preconditions:_ All devices in [code]#deviceList# must be associated with the +same platform. +_Effects:_ Constructs a [code]#context# object using the [code]#deviceList# +parameter to determine the associated platform and device. +The associated platform is the platform that contains all of the devices in +[code]#deviceList#. +The associated devices are those devices in [code]#deviceList#. +The constructed context uses the [code]#asyncHandler# parameter to handle +exceptions. +''' -[[table.members.context]] -.Member functions of the [code]#context# class -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +[[sec:context-member-funcs]] +==== Member functions + +.[apidef]#context::get_backend# +[source,role=synopsis,id=api:context-get-backend] ---- backend get_backend() const noexcept ---- - a@ Returns a [code]#backend# identifying the <> associated - with this [code]#context#. -a@ -[source] +_Returns:_ The <> that is associated with this context. + +''' + +.[apidef]#context::get_platform# +[source,role=synopsis,id=api:context-get-platform] ---- -template typename Param::return_type get_info() const +platform get_platform() const ---- - a@ Queries this SYCL [code]#context# for information requested by the - template parameter [code]#Param#. - The type alias [code]#Param::return_type# must be defined in - accordance with the info parameters in <> to - facilitate returning the type associated with the [code]#Param# - parameter. -a@ -[source] +_Returns:_ The <> that is associated with this context. + +''' + +.[apidef]#context::get_devices# +[source,role=synopsis,id=api:context-get-devices] ---- -template typename Param::return_type get_backend_info() const +std::vector get_devices() const ---- - a@ Queries this SYCL [code]#context# for <>-specific information - requested by the template parameter [code]#Param#. - The type alias [code]#Param::return_type# must be defined in - accordance with the <> specification. - Must throw an [code]#exception# with the [code]#errc::backend_mismatch# - error code if the <> that corresponds with [code]#Param# is different - from the <> that is associated with this [code]#context#. -a@ -[source] +_Returns:_ A [code]#std::vector# containing all the <> that are +associated with this context. + +''' + +.[apidef]#context::get_info# +[source,role=synopsis,id=api:context-get-info] ---- -platform get_platform() const +template +typename Param::return_type get_info() const ---- - a@ Returns the SYCL [code]#platform# that is associated with this SYCL [code]#context#. The value returned must be equal to that returned by [code]#get_info()#. -a@ -[source] +_Constraints:_ The [code]#Param# must be an information descriptor for the +context class. + +Each information descriptor specifies the return value and may also specify +preconditions, exceptions that are thrown, etc. + +''' + +.[apidef]#context::get_backend_info# +[source,role=synopsis,id=api:context-get-backend-info] ---- -std::vector get_devices() const +template +typename Param::return_type get_backend_info() const ---- - a@ Returns a [code]#std::vector# containing all SYCL [code]#devices# that are associated with this SYCL [code]#context#. The value returned must be equal to that returned by [code]#get_info()#. -|==== +_Constraints:_ The [code]#Param# must be a backend information descriptor for +the context class. + +_Throws:_ An [code]#exception# with the [code]#errc::backend_mismatch# error +code if the backend that corresponds with [code]#Param# is different from the +backend that is associated with this context. +Each information descriptor specifies the return value and may also specify +preconditions, additional exceptions that are thrown, etc. +''' -==== Context information descriptors +[[sec:context-info-descriptors]] +==== Information descriptors -A <> can be queried for information using the [code]#get_info# member -function of the [code]#context# class, specifying one of the info parameters in -[code]#info::context#. -The possible values for each info parameter and any restrictions are defined in -the specification of the <> associated with the <>. -All info parameters in [code]#info::context# are specified in -<> and the synopsis for [code]#info::context# is described -in <>. +This section describes the information descriptors that can be used as the +[code]#Param# template parameter to [api]#context::get_info#. +When the description has a _Returns_, _Throws_, etc. paragraph, this indicates +the value returned by or the exceptions thrown by the [api]#context::get_info# +function. +''' -[[table.context.info]] -.Context information descriptors -// Jon: Dims{5cm}{4.4cm}{5cm} -[width="100%",options="header",separator="@",cols="37%,19%,44%"] -|==== -@ Context Descriptors @ Return type @ Description -a@ -[source] +.[apidef]#info::context::platform# +[source,role=synopsis,id=api:info-context-platform] ---- -info::context::platform +namespace sycl::info::context { +struct platform { + using return_type = platform; +}; +} // namespace sycl::info::context ---- - @ [.code]#platform# - a@ Returns the <> associated with the <>. +_Remarks:_ Template parameter to [api]#context::get_info#. -a@ -[source] +_Returns:_ The <> that is associated with this context. + +''' + +.[apidef]#info::context::devices# +[source,role=synopsis,id=api:info-context-devices] ---- -info::context::devices +namespace sycl::info::context { +struct devices { + using return_type = std::vector; +}; +} // namespace sycl::info::context ---- - @ [.code]#std::vector# - a@ Returns all of the <> associated with the <>. +_Remarks:_ Template parameter to [api]#context::get_info#. -a@ -[source] +_Returns:_ A [code]#std::vector# containing all the <> that are +associated with this context. + +''' + +.[apidef]#info::context::atomic_memory_order_capabilities# +[source,role=synopsis,id=api:info-context-atomic-memory-order-capabilities] ---- -info::context::atomic_memory_order_capabilities +namespace sycl::info::context { +struct atomic_memory_order_capabilities { + using return_type = std::vector; +}; +} // namespace sycl::info::context ---- - @ [.code]#std::vector# - a@ This query applies only to the capabilities of atomic operations that are - applied to memory that can be concurrently accessed by multiple devices - in the context. If these capabilities are not uniform across all devices - in the context, the query reports only the capabilities that are common - for all devices. - -Returns the set of memory orders supported by these atomic operations. When a -context returns a "stronger" memory order in this set, it must also return all -"weaker" memory orders. (See <> for a definition of -"stronger" and "weaker" memory orders.) The memory orders -[code]#memory_order::acquire#, [code]#memory_order::release#, and -[code]#memory_order::acq_rel# are all the same strength. If a context returns -one of these, it must return them all. +_Remarks:_ Template parameter to [api]#context::get_info#. + +_Returns:_ This query applies only to the capabilities of atomic operations that +are applied to memory that can be concurrently accessed by multiple devices in +the context. +If these capabilities are not uniform across all devices in the context, the +query reports only the capabilities that are common for all devices. + +Returns the set of memory orders supported by these atomic operations. +When a context returns a "stronger" memory order in this set, it must also +return all "weaker" memory orders. +(See <> for a definition of "stronger" and "weaker" memory +orders.) +The memory orders [code]#memory_order::acquire#, [code]#memory_order::release#, +and [code]#memory_order::acq_rel# are all the same strength. +If a context returns one of these, it must return them all. At a minimum, each context must support [code]#memory_order::relaxed#. -a@ -[source] +''' + +.[apidef]#info::context::atomic_fence_order_capabilities# +[source,role=synopsis,id=api:info-context-atomic-fence-order-capabilities] ---- -info::context::atomic_fence_order_capabilities +namespace sycl::info::context { +struct atomic_fence_order_capabilities { + using return_type = std::vector; +}; +} // namespace sycl::info::context ---- - @ [.code]#std::vector# - a@ This query applies only to the capabilities of [code]#atomic_fence# when - applied to memory that can be concurrently accessed by multiple devices - in the context. If these capabilities are not uniform across all devices - in the context, the query reports only the capabilities that are common - for all devices. +_Remarks:_ Template parameter to [api]#context::get_info#. + +_Returns:_ This query applies only to the capabilities of [code]#atomic_fence# +when applied to memory that can be concurrently accessed by multiple devices in +the context. +If these capabilities are not uniform across all devices in the context, the +query reports only the capabilities that are common for all devices. Returns the set of memory orders supported by these [code]#atomic_fence# -operations. When a context returns a "stronger" memory order in this set, it -must also return all "weaker" memory orders. (See <> for -a definition of "stronger" and "weaker" memory orders.) +operations. +When a context returns a "stronger" memory order in this set, it must also +return all "weaker" memory orders. +(See <> for a definition of "stronger" and "weaker" memory +orders.) At a minimum, each context must support [code]#memory_order::relaxed#, [code]#memory_order::acquire#, [code]#memory_order::release#, and [code]#memory_order::acq_rel#. -a@ -[source] +''' + +.[apidef]#info::context::atomic_memory_scope_capabilities# +[source,role=synopsis,id=api:info-context-atomic-memory-scope-capabilities] ---- -info::context::atomic_memory_scope_capabilities +namespace sycl::info::context { +struct atomic_memory_scope_capabilities { + using return_type = std::vector; +}; +} // namespace sycl::info::context ---- - @ [.code]#std::vector# - a@ Returns the set of memory scopes supported by atomic operations on all - devices in the context. When a context returns a "wider" memory scope - in this set, it must also return all "narrower" memory scopes. (See - <> for a definition of "wider" and "narrower" scopes.) - At a minimum, each context must support [code]#memory_scope::work_item#, - [code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#. +_Remarks:_ Template parameter to [api]#context::get_info#. -a@ -[source] +_Returns:_ The set of memory scopes supported by atomic operations on all +devices in the context. +When a context returns a "wider" memory scope in this set, it must also return +all "narrower" memory scopes. +(See <> for a definition of "wider" and "narrower" scopes.) +At a minimum, each context must support [code]#memory_scope::work_item#, +[code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#. + +''' + +.[apidef]#info::context::atomic_fence_scope_capabilities# +[source,role=synopsis,id=api:info-context-atomic-fence-scope-capabilities] ---- -info::context::atomic_fence_scope_capabilities +namespace sycl::info::context { +struct atomic_fence_scope_capabilities { + using return_type = std::vector; +}; +} // namespace sycl::info::context ---- - @ [.code]#std::vector# - a@ Returns the set of memory orderings supported by [code]#atomic_fence# on - all devices in the context. When a context returns a "wider" memory - scope in this set, it must also return all "narrower" memory scopes. - (See <> for a definition of "wider" and "narrower" - scopes.) At a minimum, each context must support - [code]#memory_scope::work_item#, [code]#memory_scope::sub_group#, and - [code]#memory_scope::work_group#. - -|==== +_Remarks:_ Template parameter to [api]#context::get_info#. +_Returns:_ The set of memory orderings supported by [code]#atomic_fence# on all +devices in the context. +When a context returns a "wider" memory scope in this set, it must also return +all "narrower" memory scopes. +(See <> for a definition of "wider" and "narrower" scopes.) +At a minimum, each context must support [code]#memory_scope::work_item#, +[code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#. +''' [[sec:context-properties]] -==== Context properties +==== Properties The [code]#property_list# constructor parameters are present for extensibility. + // \input{device_class} // %%%%%%%%%%%%%%%%%%%%%%%%%%%% begin device_class %%%%%%%%%%%%%%%%%%%%%%%%%%%% From 305fd066238cafbe01e0af27d0a585ddac12c8b7 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 25 Jul 2024 17:43:06 -0400 Subject: [PATCH 2/2] Add reference to context info descriptors Add a link from `context::get_info` to the section defining the context information descriptors. --- adoc/chapters/programming_interface.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index ceac81e3..b44b4474 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1294,6 +1294,8 @@ context class. Each information descriptor specifies the return value and may also specify preconditions, exceptions that are thrown, etc. +See <> for the context information descriptors +that are defined by the <>. '''