diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 5bbf7ba4..5eeb6d88 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]#Construct from device# -[source,role=synopsis,id=api:context-ctor-dev] +.[apititle]#Constructor with device# +[source,role=synopsis,id=api:context-ctor-device] ---- -explicit context(const device& dev, async_handler asyncHandler = {}) +explicit context(const device& dev, 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 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]#Constructor with platform# +[source,role=synopsis,id=api:context-ctor-platform] +---- +explicit context(const platform &plt, 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#. + +_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the +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 = {}) +---- + +_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]#Construct from device list# -[source,role=synopsis,id=api:context-ctor-dev-list] +.[apititle]#Constructor with device list# +[source,role=synopsis,id=api:context-ctor-device-list] ---- -explicit context(const std::vector& deviceList, - async_handler asyncHandler = {}) +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 4608ab44..59c60034 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 = {});