.. default-domain:: chpl

.. module:: AutoGpu
   :synopsis: Automatically included GPU symbols 

AutoGpu
=======
.. note::

   All Chapel programs automatically ``use`` this module by default.
   An explicit ``use`` statement is not necessary.

.. warning::

   The module name 'AutoGpu' is unstable.

Automatically included GPU symbols 

.. annotation:: attribute @gpu.assertEligible

   
   This attribute can be applied to loops to ensure that they are eligible
   for GPU execution. Unlike :annotation:`@assertOnGpu`, this attribute has no
   execution-time effect. It only asserts that the code `could` be executed on
   the GPU, and not that it `will` be executed.
   
   
   .. code-block:: chapel
   
     @gpu.assertEligible
     foreach i in 1..128 { /* ... */ }
   
     // variable version (applies to loop expressions and promoted expressions)
     @gpu.assertEligible
     var A = (foreach i in 1..128 do i*i) + 1;
   

.. data:: config param silenceAssertOnGpuWarning = false

   
   This configuration parameter is used to disable warnings that are emitted
   when :annotation:`@assertOnGpu` is used in a non-GPU compilation. Since
   :annotation:`@assertOnGpu`'s execution-time semantics are to halt execution
   if it is not on the GPU, it will always halt execution when the program is
   not compiled for the GPU. This is likely an issue, so the warning is emitted
   by default. However, in case the user is aware of this and wants to silence
   the warning, they can set this configuration parameter to ``true``.
   

.. annotation:: attribute @assertOnGpu

   
   This attribute can be applied to loops to ensure that they are executed on
   the GPU. It has the effect of :annotation:`@gpu.assertEligible`, halting
   compilation if the construct it is applied to cannot be executed on the GPU.
   In addition, this attribute causes an execution-time check to be performed
   when it is reached, ensuring that the code is executed on the GPU.
   
   .. code-block:: chapel
   
     @assertOnGpu
     foreach i in 1..128 { /* ... */ }
   
     // variable version (applies to loop expressions and promoted expressions)
     @assertOnGpu
     var A = (foreach i in 1..128 do i*i) + 1;
   

.. annotation:: attribute @gpu.blockSize(blockSize: integral)

   
   This attribute can be applied to loops to specify the GPU block size to use
   when executing the loop on the GPU.
   
   .. code-block:: chapel
   
     // loop version
     @gpu.blockSize(64)
     foreach i in 1..128 { /* ... */ }
   
     // variable version (applies to loop expressions and promoted expressions)
     @gpu.blockSize(64)
     var A = (foreach i in 1..128 do i*i) + 1;
   

.. annotation:: attribute @gpu.itersPerThread(itersPerThread: integral, param cyclic: bool = false)

   
   This attribute requests that the kernel executes each consecutive
   ``numIters`` iterations of the affected loop sequentially within the same
   GPU thread. Users must ensure that the arguments to this attribute are
   positive.
   
   .. code-block:: chapel
   
     // loop version
     @gpu.itersPerThread(4)
     foreach i in 1..128 { /* ... */ }
   
     // variable version (applies to loop expressions and promoted expressions)
     @gpu.itersPerThread(4)
     var A = (foreach i in 1..128 do i*i) + 1;
   
   Specifying the `cyclic` argument to be `true` distributes the iterations
   across GPU threads in cyclic fashion instead of the default block
   discipline.