Specify that implementations may choose to not use secondary queues

This commit changes the specification for the submit function taking a
secondary queue, specifying that implementations may choose to not
associate the secondary queue with the command-groups. In tandem with
this, the changes use the term "associated" in more places to make it
clearer that cases requiring exceptions for secondary queues are only if
the implementations elect to associate the secondary queues with the
command-groups.

Signed-off-by: Larsen, Steffen <[email protected]>

Author: steffenlarsen

adoc/chapters/device_compiler.adoc

@@ -424,12 +424,12 @@ implementation supports the features on any of its devices.
 Of course, applications that make use of optional kernel features should ensure
 that a kernel using such a feature is submitted only to a device that supports
 the feature.
-If the application submits a <<command-group>> using a secondary queue, then any
-kernel submitted from the <<command-group>> should use only features that are
-supported by both the primary queue's device and the secondary queue's device.
-If an application fails to do this, the implementation must throw a synchronous
-exception with the [code]#errc::kernel_not_supported# error code from the
-<<kernel-invocation-command>> (e.g. [code]#parallel_for()#).
+If the application submits a <<command-group>> that has a secondary queue
+associated with it, then any kernel submitted from the <<command-group>> should
+use only features that are supported by both the primary queue's device and the
+secondary queue's device. If an application fails to do this, the implementation
+must throw a synchronous exception with the [code]#errc::kernel_not_supported#
+error code from the <<kernel-invocation-command>> (e.g. [code]#parallel_for()#).
 
 It is legal for a SYCL application to define several kernels in the same
 translation unit even if they use different optional features, as shown in the
@@ -630,10 +630,10 @@ Specifying this attribute on a kernel has two effects.  First, it causes the
 [code]#errc::kernel_not_supported# error code if the kernel is submitted to a
 device that does not have one of the listed aspects.  (This includes the device
 associated with the secondary queue if the kernel is submitted from a
-<<command-group>> that has a secondary queue.)  Second, it causes the compiler
-to issue a diagnostic if the kernel (or any of the functions it calls) uses an
-optional feature that is associated with an aspect that is not listed in the
-attribute.
+<<command-group>> with an associated secondary queue.)  Second, it causes the
+compiler to issue a diagnostic if the kernel (or any of the functions it calls)
+uses an optional feature that is associated with an aspect that is not listed in
+the attribute.
 
 The value of each parameter to this attribute must be equal to one of the
 values in the [code]#sycl::aspect# enumeration type (including any extended

adoc/chapters/programming_interface.adoc

@@ -4150,6 +4150,10 @@ device.
 On a kernel error, this <<command-group-function-object>> may be scheduled for
 execution on the secondary queue [code]#secondaryQueue# as described in
 <<sec::fallback-mechanism>>.
+The implementation may elect to not use the secondary queue
+[code]#secondaryQueue#, in which case the secondary queue is not considered
+associated with the enqueued <<command-group>> and any <<handler>> object passed
+to it.
 
 _Returns:_ An event which represents the <<command>> which is submitted to the
 queue.
@@ -5533,10 +5537,10 @@ via the SYCL [code]#device# class info query
 the implementation to throw an [code]#exception# with the [code]#errc::invalid#
 error code from the [code]#accessor# constructor (if the accessor is not a
 placeholder) or from [code]#handler::require()# (if the accessor is a
-placeholder).  If the accessor is bound to a <<command-group>> with a secondary
-queue, the sub-buffer's alignment must be compatible with both the primary
-queue's device and the secondary queue's device, otherwise this exception is
-thrown.
+placeholder).  If the accessor is bound to a <<command-group>> with an
+associated secondary queue, the sub-buffer's alignment must be compatible with
+both the primary queue's device and the secondary queue's device, otherwise this
+exception is thrown.
 
 Must throw an [code]#exception# with the [code]#errc::invalid# error code if
 [code]#b# is a sub-buffer.
@@ -14600,7 +14604,8 @@ implicitly uses the kernel bundle that contains the [code]#kernelObject#.
 Throws an [code]#exception# with the [code]#errc::kernel_not_supported# error
 code if the [code]#kernelObject# is not compatible with either the device
 associated with the primary queue of the <<command-group>> or with the device
-associated with the secondary queue (if specified).
+associated with the secondary queue (if one is associated with the
+<<command-group>>).
 
 a@
 [source]
@@ -14622,7 +14627,8 @@ implicitly uses the kernel bundle that contains the [code]#kernelObject#.
 Throws an [code]#exception# with the [code]#errc::kernel_not_supported# error
 code if the [code]#kernelObject# is not compatible with either the device
 associated with the primary queue of the <<command-group>> or with the device
-associated with the secondary queue (if specified).
+associated with the secondary queue (if one is associated with the
+<<command-group>>).
 
 a@
 [source]
@@ -14649,7 +14655,8 @@ implicitly uses the kernel bundle that contains the [code]#kernelObject#.
 Throws an [code]#exception# with the [code]#errc::kernel_not_supported# error
 code if the [code]#kernelObject# is not compatible with either the device
 associated with the primary queue of the <<command-group>> or with the device
-associated with the secondary queue (if specified).
+associated with the secondary queue (if one is associated with the
+<<command-group>>).
 
 |====
 
@@ -15280,10 +15287,10 @@ If the <<command-group>> attempts to invoke a kernel that is not contained by a
 compatible device image in [code]#execBundle#, the <<kernel-invocation-command>>
 throws a synchronous [code]#exception# with the
 [code]#errc::kernel_not_supported# error code.
-If the <<command-group>> has a secondary queue, then the [code]#execBundle# must
-contain a kernel that is compatible with both the primary queue's device and the
-secondary queue's device, otherwise the <<kernel-invocation-command>> throws
-this exception.
+If the <<command-group>> has an associated secondary queue, then the
+[code]#execBundle# must contain a kernel that is compatible with both the
+primary queue's device and the secondary queue's device, otherwise the
+<<kernel-invocation-command>> throws this exception.
 
 Since the handler method for setting specialization constants is incompatible
 with the kernel bundle method, applications should not call this function if
@@ -15295,8 +15302,9 @@ _Throws:_
   * An [code]#exception# with the [code]#errc::invalid# error code if the
     <<context>> associated with the <<handler>> via its associated primary
     <<queue>> or the <<context>> associated with the secondary <<queue>> (if
-    provided) is different from the <<context>> associated with the
-    <<kernel-bundle>> specified by [code]#execBundle#.
+    (if one is associated with the <<handler>>) is different from the
+    <<context>> associated with the <<kernel-bundle>> specified by
+    [code]#execBundle#.
 
   * An [code]#exception# with the [code]#errc::invalid# error code if
     [code]#handler::set_specialization_constant()# has been called for this
@@ -15727,8 +15735,8 @@ code if [code]#Backend != get_backend()#.
 --
 _Returns:_ The <<native-backend-object>> associated with the <<queue>> that the
 <<host-task>> was submitted to.
-If the <<command-group>> was submitted with a secondary <<queue>> and the
-fall-back was triggered, the <<queue>> that is associated with the
+If the <<command-group>> was submitted with an associated secondary <<queue>>
+and the fall-back was triggered, the <<queue>> that is associated with the
 [code]#interop_handle# must be the fall-back <<queue>>.
 The <<native-backend-object>> returned must be in a state where it is capable of
 being used in a way appropriate for the associated <<backend>>.
@@ -17468,7 +17476,7 @@ then:
 ==== Asynchronous errors with a secondary queue
 
 If an <<async-error>> occurs when running or enqueuing a command group which has
-a secondary queue specified, then the command group may be enqueued to the
+a secondary queue associated, then the command group may be enqueued to the
 secondary queue instead of the primary queue.
 The error handling in this case is also configured using the <<async-handler>>
 provided for both queues.
@@ -17480,10 +17488,10 @@ If the primary queue fails and there is an <<async-handler>> given at this
 queue's construction, which populates the [code]#exception_list# parameter, then
 any errors will be added and can be thrown whenever the user chooses to handle
 those exceptions.
-Since there were errors on the primary queue and a secondary queue was given,
-then the execution of the kernel is re-scheduled to the secondary queue and any
-error reporting for the kernel execution on that queue is done through that
-queue, in the same way as described above.
+Since there were errors on the primary queue and a secondary queue was
+associated, then the execution of the kernel is re-scheduled to the secondary
+queue and any error reporting for the kernel execution on that queue is done
+through that queue, in the same way as described above.
 The secondary queue may fail as well, and the errors will be thrown if there is
 an <<async-handler>> and either [code]#wait_and_throw()# or [code]#throw()# are
 called on that queue.