gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchadd.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: ATOMIC_FETCH_ADD, Atomic subroutine, ADD with fetch
   7
   8 .. _atomic_fetch_add:
   9
  10 ATOMIC_FETCH_ADD --- Atomic ADD operation with prior fetch
  11 **********************************************************
  12
  13 .. function:: ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)
  14
  15   ``ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)`` atomically stores the value of
  16   :samp:`{ATOM}` in :samp:`{OLD}` and adds the value of :samp:`{VALUE}` to the
  17   variable :samp:`{ATOM}`. When :samp:`{STAT}` is present and the invocation was
  18   successful, it is assigned the value 0. If it is present and the invocation
  19   has failed, it is assigned a positive value; in particular, for a coindexed
  20   :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of
  21   ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has
  22   failed, the value ``STAT_FAILED_IMAGE``.
  23
  24   :param ATOM:
  25     Scalar coarray or coindexed variable of integer
  26     type with ``ATOMIC_INT_KIND`` kind.
  27     ``ATOMIC_LOGICAL_KIND`` kind.
  28
  29   :param VALUE:
  30     Scalar of the same type as :samp:`{ATOM}`. If the kind
  31     is different, the value is converted to the kind of :samp:`{ATOM}`.
  32
  33   :param OLD:
  34     Scalar of the same type and kind as :samp:`{ATOM}`.
  35
  36   :param STAT:
  37     (optional) Scalar default-kind integer variable.
  38
  39   Standard:
  40     TS 18508 or later
  41
  42   Class:
  43     Atomic subroutine
  44
  45   Syntax:
  46     .. code-block:: fortran
  47
  48       CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])
  49
  50   Example:
  51     .. code-block:: fortran
  52
  53       program atomic
  54         use iso_fortran_env
  55         integer(atomic_int_kind) :: atom[*], old
  56         call atomic_add (atom[1], this_image(), old)
  57       end program atomic
  58
  59   See also:
  60     :ref:`ATOMIC_DEFINE`,
  61     :ref:`ATOMIC_ADD`,
  62     :ref:`ISO_FORTRAN_ENV`,
  63     :ref:`ATOMIC_FETCH_AND`,
  64     :ref:`ATOMIC_FETCH_OR`,
  65     :ref:`ATOMIC_FETCH_XOR`