From 3cc87507efa5164df8c3395921b29b06fe40745f Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 17 Sep 2024 12:57:11 -0400 Subject: [PATCH] Improve wording about returned event 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". --- adoc/chapters/programming_interface.adoc | 45 +++++++++++++++--------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index ebc0cda7..756cdbbf 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -3225,11 +3225,12 @@ template event submit(T cgf) ---- -_Effects:_ Submit a <> to the queue, in order to -be scheduled for execution on the device. +_Effects:_ Immediately calls the <> [code]#cgf#, +which may submit no more than one <> to the queue for execution on the +device. -_Returns:_ An event which the application can use to determine when the -<> associated with the <> has completed. +_Returns:_ An event which represents the <> which is submitted to the +queue. ''' @@ -3240,14 +3241,15 @@ template event submit(T cgf, queue& secondaryQueue) ---- -_Effects:_ Submit a <> to the queue, in order to -be scheduled for execution on the device. +_Effects:_ Immediately calls the <> [code]#cgf#, +which may submit no more than one <> to the queue for execution on the +device. On a kernel error, this <> may be scheduled for execution on the secondary queue [code]#secondaryQueue# as described in <>. -_Returns:_ An event which the application can use to determine when the -<> associated with the <> has completed. +_Returns:_ An event which represents the <> which is submitted to the +queue. If the command is scheduled on [code]#secondaryQueue#, the event is associated with that queue. @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. ''' @@ -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 <> which is submitted to the +queue. '''