Skip to content

Commit

Permalink
Improve wording about returned event
Browse files Browse the repository at this point in the history
Improve the wording of the event that is returned by `queue::submit` and
friends.

Since the new wording says that the event represents the *command* that
is submitted to the queue, it seemed awkward for the _Effects_ paragraph
to say that a *command group function* is submitted to the queue.  I
replaced this with wording saying that the command group function is
immediately called, which is consistent with what we say in the
introductory paragraphs of section 4.6.5 "Queue class".  The new wording
also notes that the command group function may submit no more than one
command to the queue, which is consistent with the existing wording in
section 4.9.3 "Command group scope".
  • Loading branch information
gmlueck committed Sep 17, 2024
1 parent 46907d4 commit 3cc8750
Showing 1 changed file with 28 additions and 17 deletions.
45 changes: 28 additions & 17 deletions adoc/chapters/programming_interface.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -3225,11 +3225,12 @@ template <typename T>
event submit(T cgf)
----

_Effects:_ Submit a <<command-group-function-object>> to the queue, in order to
be scheduled for execution on the device.
_Effects:_ Immediately calls the <<command-group-function-object>> [code]#cgf#,
which may submit no more than one <<command>> to the queue for execution on the
device.

_Returns:_ An event which the application can use to determine when the
<<command>> associated with the <<command-group-function-object>> has completed.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3240,14 +3241,15 @@ template <typename T>
event submit(T cgf, queue& secondaryQueue)
----

_Effects:_ Submit a <<command-group-function-object>> to the queue, in order to
be scheduled for execution on the device.
_Effects:_ Immediately calls the <<command-group-function-object>> [code]#cgf#,
which may submit no more than one <<command>> to the queue for execution on the
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>>.

_Returns:_ An event which the application can use to determine when the
<<command>> associated with the <<command-group-function-object>> has completed.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.
If the command is scheduled on [code]#secondaryQueue#, the event is associated
with that queue.

Expand Down Expand Up @@ -3360,7 +3362,8 @@ _Effects (3):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::single_task(kernelFunc)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand Down Expand Up @@ -3412,7 +3415,8 @@ _Effects (6):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::parallel_for(executionRange, rest)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3438,7 +3442,8 @@ _Effects (3):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::memcpy(dest, src, numBytes)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand Down Expand Up @@ -3515,7 +3520,8 @@ _Effects (8):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::require(src)#,
[code]#handler::require(dest)#, and [code]#handler::copy(src, dest)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3541,7 +3547,8 @@ _Effects (3):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::memcpy(ptr, value, numBytes)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand Down Expand Up @@ -3578,7 +3585,8 @@ _Effects (4):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::require(dest)# and
[code]#handler::fill(dest, src)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3603,7 +3611,8 @@ _Effects (3):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::prefetch(ptr, numBytes)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3629,7 +3638,8 @@ _Effects (3):_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::depends_on(depEvents)# and
[code]#handler::mem_advise(ptr, numBytes, advice)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand All @@ -3645,7 +3655,8 @@ _Effects:_ Equivalent to calling [api]#queue::submit# with a command group
function that calls [code]#handler::require(acc)# and
[code]#handler::update_host(acc)#.

_Returns:_ An event which represents the command that is submitted to the queue.
_Returns:_ An event which represents the <<command>> which is submitted to the
queue.

'''

Expand Down

0 comments on commit 3cc8750

Please sign in to comment.