From a4543c62ce50926127e09e1a1e52fe78b6cb1f02 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Fri, 20 Sep 2024 17:39:56 -0400 Subject: [PATCH 1/2] Fix contradiction with context constructors The context constructor overloads in the `context` synopsis did not match the description in the text of the specification. We decided that the overloads in the synopsis were what we intended, so change the text to match. We also discovered that two constructor overloads taking a `platform` argument were present in SYCL 1.2.1 and were inadvertently dropped from the SYCL 2020 specification. Add them back. Clarify the behavior of the constructors when the set of devices is empty. We decided that this should throw an exception, which is consistent with OpenCL's `clCreateContext`. Closes #470 Closes #474 --- adoc/chapters/programming_interface.adoc | 140 ++++++++++++++++++----- adoc/headers/context.h | 5 + 2 files changed, 118 insertions(+), 27 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 1418e45f5..967ba2728 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1227,56 +1227,141 @@ include::{header_dir}/context.h[lines=4..-1] [[sec:context-ctors]] ==== Constructors +All context constructors take a parameter named [code]#propList# which allows +the application to pass zero or more properties. +These properties may specify additional effects of the constructor and may also +specify exceptions that the constructor throws. +See <> for the context properties that are defined by +the <>. + +''' + .[apititle]#Default constructor# [source,role=synopsis,id=api:context-ctor] ---- -explicit context(async_handler asyncHandler = {}) +explicit context(const property_list& propList = {}) ---- -_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 +_Effects:_ Constructs a [code]#context# object using 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 +The context's platform is the platform that contains this device. +The context contains the selected device. +The context may also contain other devices from the same platform. +Whether this happens is implementation defined. + +''' + +.[apititle]#Constructor with async handler# +[source,role=synopsis,id=api:context-ctor-async-handler] +---- +explicit context(async_handler asyncHandler, const property_list& propList = {}) +---- + +_Effects:_ Constructs a [code]#context# object using the device selected by [code]#default_selector_v#. -The constructed context uses the [code]#asyncHandler# parameter to handle -exceptions. +The context's platform is the platform that contains this device. +The context contains the selected device. +The context may also contain other devices from the same platform. +Whether this happens is implementation defined. +The context has the asynchronous error handler [code]#asyncHandler#. + +''' + +.[apititle]#Constructor with device# +[source,role=synopsis,id=api:context-ctor-device] +---- +explicit context(const device& dev, const property_list& propList = {}) +---- + +_Effects:_ Constructs a [code]#context# object that contains the device +[code]#dev#. +The context's platform is the platform that contains [code]#dev#. + +''' + +.[apititle]#Constructor with device and async handler# +[source,role=synopsis,id=api:context-ctor-device-async-handler] +---- +explicit context(const device& dev, async_handler asyncHandler, + const property_list& propList = {}) +---- + +_Effects:_ Constructs a [code]#context# object that contains the device +[code]#dev#. +The context's platform is the platform that contains [code]#dev#. +The context has the asynchronous error handler [code]#asyncHandler#. ''' -.[apititle]#Construct from device# -[source,role=synopsis,id=api:context-ctor-dev] +.[apititle]#Constructor with platform# +[source,role=synopsis,id=api:context-ctor-platform] ---- -explicit context(const device& dev, async_handler asyncHandler = {}) +explicit context(const platform &plt, const property_list &propList = {}) ---- -_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. +_Effects:_ Constructs a [code]#context# object that contains all of the devices +in the platform [code]#plt#. +The context's platform is [code]#plt#. + +_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the +platform [code]#plt# contains no devices. ''' -.[apititle]#Construct from device list# -[source,role=synopsis,id=api:context-ctor-dev-list] +.[apititle]#Constructor with platform and async handler# +[source,role=synopsis,id=api:context-ctor-platform-async-handler] ---- -explicit context(const std::vector& deviceList, - async_handler asyncHandler = {}) +explicit context(const platform &plt, async_handler asyncHandler, + const property_list &propList = {}) +---- + +_Effects:_ Constructs a [code]#context# object that contains all of the devices +in the platform [code]#plt#. +The context's platform is [code]#plt#. +The context has the asynchronous error handler [code]#asyncHandler#. + +_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the +platform [code]#plt# contains no devices. + +''' + +.[apititle]#Constructor with device list# +[source,role=synopsis,id=api:context-ctor-device-list] +---- +explicit context(const std::vector& deviceList, const property_list& propList = {}) ---- _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 +_Effects:_ Constructs a [code]#context# object that contains all of the devices +in [code]#deviceList#. +The context's platform is the platform that contains 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. + +_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if +[code]#deviceList# is empty. + +''' + +.[apititle]#Constructor with device list and async handler# +[source,role=synopsis,id=api:context-ctor-device-list-async-handler] +---- +explicit context(const std::vector& deviceList, async_handler asyncHandler, + const property_list& propList = {}) +---- + +_Preconditions:_ All devices in [code]#deviceList# must be associated with the +same platform. + +_Effects:_ Constructs a [code]#context# object that contains all of the devices +in [code]#deviceList#. +The context's platform is the platform that contains the devices in +[code]#deviceList#. +The context has the asynchronous error handler [code]#asyncHandler#. + +_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if +[code]#deviceList# is empty. ''' @@ -1503,6 +1588,7 @@ At a minimum, each context must support [code]#memory_scope::work_item#, [[sec:context-properties]] ==== Properties +The <> does not define any properties for the context constructors. The [code]#property_list# constructor parameters are present for extensibility. diff --git a/adoc/headers/context.h b/adoc/headers/context.h index 4608ab441..59c600341 100644 --- a/adoc/headers/context.h +++ b/adoc/headers/context.h @@ -14,6 +14,11 @@ class context { explicit context(const device& dev, async_handler asyncHandler, const property_list& propList = {}); + explicit context(const platform &plt, const property_list &propList = {}); + + explicit context(const platform &plt, async_handler asyncHandler, + const property_list &propList = {}); + explicit context(const std::vector& deviceList, const property_list& propList = {}); From 2887f9c78fefb810ad97eefcee854779a26d269b Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 9 Jan 2025 11:40:55 -0500 Subject: [PATCH 2/2] Fix style for "&" in function parameters --- adoc/chapters/programming_interface.adoc | 6 +++--- adoc/headers/context.h | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 967ba2728..7479e573f 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1296,7 +1296,7 @@ The context has the asynchronous error handler [code]#asyncHandler#. .[apititle]#Constructor with platform# [source,role=synopsis,id=api:context-ctor-platform] ---- -explicit context(const platform &plt, const property_list &propList = {}) +explicit context(const platform& plt, const property_list& propList = {}) ---- _Effects:_ Constructs a [code]#context# object that contains all of the devices @@ -1311,8 +1311,8 @@ platform [code]#plt# contains no devices. .[apititle]#Constructor with platform and async handler# [source,role=synopsis,id=api:context-ctor-platform-async-handler] ---- -explicit context(const platform &plt, async_handler asyncHandler, - const property_list &propList = {}) +explicit context(const platform& plt, async_handler asyncHandler, + const property_list& propList = {}) ---- _Effects:_ Constructs a [code]#context# object that contains all of the devices diff --git a/adoc/headers/context.h b/adoc/headers/context.h index 59c600341..740f4ed93 100644 --- a/adoc/headers/context.h +++ b/adoc/headers/context.h @@ -14,10 +14,10 @@ class context { explicit context(const device& dev, async_handler asyncHandler, const property_list& propList = {}); - explicit context(const platform &plt, const property_list &propList = {}); + explicit context(const platform& plt, const property_list& propList = {}); - explicit context(const platform &plt, async_handler asyncHandler, - const property_list &propList = {}); + explicit context(const platform& plt, async_handler asyncHandler, + const property_list& propList = {}); explicit context(const std::vector& deviceList, const property_list& propList = {});