Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify default context behavior #623

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Clarify default context behavior #623

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5f812f7
Clarify default context behavior
gmlueck Sep 17, 2024
9075baa
Reword as suggested by Thomas
gmlueck Sep 19, 2024
2d63525
Reword description of default context
gmlueck Oct 7, 2024
013b3a8
Fix reflow
gmlueck Oct 7, 2024
da50947
Reword description of default context again
gmlueck Oct 8, 2024
3a69290
Clarify that default context contains root devices
gmlueck Nov 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 40 additions & 11 deletions adoc/chapters/programming_interface.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -969,6 +969,15 @@ The [code]#platform# class also provides constructors, but constructing a new
[code]#platform# instance merely creates a new object that is a copy of one of
the objects returned by [api]#platform::get_platforms#.

Each platform has an associated default context which contains all of the
<<root-device,root devices>> in the platform.
This default context does not have an asynchronous error handler.
Applications can retrieve a copy of this default `context` object, for example,
by constructing a `queue`.
These copies follow the common reference semantics, as though they are all
copies of an internal per-platform `context` object representing the platform's
default context.

The [code]#platform# class provides the common reference semantics as defined in
<<sec:reference-semantics>>.

Expand Down Expand Up @@ -2936,10 +2945,6 @@ 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.

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

_Effects:_ Constructs a [code]#queue# object using the device selected by
[code]#default_selector_v#.
The queue's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.

'''

Expand All @@ -2991,6 +2999,9 @@ explicit queue(const async_handler& asyncHandler,

_Effects:_ Constructs a [code]#queue# object using the device selected by
[code]#default_selector_v#.
The queue's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.
The queue has the asynchronous error handler [code]#asyncHandler#.

'''
Expand All @@ -3010,6 +3021,9 @@ 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's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.

'''

Expand All @@ -3029,6 +3043,9 @@ 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's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.
The queue has the asynchronous error handler [code]#asyncHandler#.

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

_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.

'''

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

_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue's platform is the platform that contains this device.
The queue's context is this platform's default context as described in
<<sec:platform-class>>.
The queue has the asynchronous error handler [code]#asyncHandler#.

'''
Expand All @@ -3072,7 +3095,8 @@ 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 context [code]#syclContext#.
The queue's platform is the platform that contains this device.
The queue's context is [code]#syclContext#.

_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if
[code]#syclContext# does not contain the device selected by
Expand All @@ -3096,8 +3120,9 @@ 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 context [code]#syclContext# and the asynchronous error handler
[code]#asyncHandler#.
The queue's platform is the platform that contains this device.
The queue's context is [code]#syclContext#.
The queue has the asynchronous error handler [code]#asyncHandler#.

_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if
[code]#syclContext# does not contain the device selected by
Expand All @@ -3112,8 +3137,10 @@ explicit queue(const context& syclContext, const device& syclDevice,
const property_list& propList = {})
----

_Effects:_ Constructs a [code]#queue# object using the device [code]#syclDevice#
and the context [code]#syclContext#.
_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue's platform is the platform that contains this device.
The queue's context is [code]#syclContext#.

_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code unless
[code]#syclDevice# is contained by [code]#syclContext# or is a
Expand All @@ -3129,8 +3156,10 @@ explicit queue(const context& syclContext, const device& syclDevice,
const property_list& propList = {})
----

_Effects:_ Constructs a [code]#queue# object using the device [code]#syclDevice#
and the context [code]#syclContext#.
_Effects:_ Constructs a [code]#queue# object using the device
[code]#syclDevice#.
The queue's platform is the platform that contains this device.
The queue's context is [code]#syclContext#.
The queue has the asynchronous error handler [code]#asyncHandler#.

_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code unless
Expand Down