Skip to content

Commit

Permalink
Clarify default context behavior
Browse files Browse the repository at this point in the history
Clarify that the `queue` constructors that do not take a `context`
parameter use the platform's default context.

The WG decided to make this as a clarification to the SYCL 2020
specification because:

* DPC++ has always behaved this way, and AdaptiveCpp mostly behaves this
  way now.

* It would be difficult to enable this as an extension because it
  doesn't add any new API.  Therefore, an application could end up
  relying on the "default context" behavior without the author of the
  application even being aware that the application is using extended
  behavior.
  • Loading branch information
gmlueck committed Sep 26, 2024
1 parent 0940312 commit 5f812f7
Showing 1 changed file with 15 additions and 3 deletions.
18 changes: 15 additions & 3 deletions adoc/chapters/programming_interface.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2936,9 +2936,15 @@ passing <<async-error,asynchronous errors>> at specific times to an
The application can wait for all <<command-group,command groups>> submitted to a
queue calling [api]#queue::wait# or [api]#queue::wait_and_throw#.

All constructors of the [code]#queue# class implicitly construct a
[code]#platform#, [code]#device#, and [code]#context# in order to facilitate the
construction of the queue.
All [code]#queue# objects have an associated device, platform, and context which
are determined by the constructor.
The description of each constructor below tells how the device is chosen, and
the platform is always the platform that contains this device.
The description of each constructor also tells how the context is chosen.
When the constructor does not take a context object as a parameter, the queue
uses the platform's default context.
Each platform has a single context object which is used as its default context,
and that context object contains all of the devices in the platform.

A queue may be destroyed even when there are uncompleted <<command, commands>>
that have been submitted to the queue.
Expand Down Expand Up @@ -2979,6 +2985,7 @@ explicit queue(const property_list& propList = {})

_Effects:_ Constructs a [code]#queue# object using the device selected by
[code]#default_selector_v#.
The queue has the default context of the platform that contains this device.

'''

Expand All @@ -2991,6 +2998,7 @@ explicit queue(const async_handler& asyncHandler,

_Effects:_ Constructs a [code]#queue# object using the device selected by
[code]#default_selector_v#.
The queue has the default context of the platform that contains this device.
The queue has the asynchronous error handler [code]#asyncHandler#.

'''
Expand All @@ -3010,6 +3018,7 @@ satisfies the requirements of a <<device-selector>> as defined in
_Effects:_ The [code]#deviceSelector# is called for every <<root-device>> as
described in <<sec:device-selector>>, and a [code]#queue# object is constructed
using the device it selects.
The queue has the default context of the platform that contains this device.

'''

Expand All @@ -3029,6 +3038,7 @@ satisfies the requirements of a <<device-selector>> as defined in
_Effects:_ The [code]#deviceSelector# is called for every <<root-device>> as
described in <<sec:device-selector>>, and a [code]#queue# object is constructed
using the device it selects.
The queue has the default context of the platform that contains this device.
The queue has the asynchronous error handler [code]#asyncHandler#.

'''
Expand All @@ -3041,6 +3051,7 @@ explicit queue(const device& syclDevice, const property_list& propList = {})

_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue has the default context of the platform that contains this device.

'''

Expand All @@ -3053,6 +3064,7 @@ explicit queue(const device& syclDevice, const async_handler& asyncHandler,

_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue has the default context of the platform that contains this device.
The queue has the asynchronous error handler [code]#asyncHandler#.

'''
Expand Down

0 comments on commit 5f812f7

Please sign in to comment.