gcc/fortran/doc/gfortran/intrinsic-procedures/atomicref.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_REF, Atomic subroutine, reference
   7
   8 .. _atomic_ref:
   9
  10 ATOMIC_REF --- Obtaining the value of a variable atomically
  11 ***********************************************************
  12
  13 .. function:: ATOMIC_REF(VALUE, ATOM , STAT)
  14
  15   ``ATOMIC_DEFINE(ATOM, VALUE)`` atomically assigns the value of the
  16   variable :samp:`{ATOM}` to :samp:`{VALUE}`. When :samp:`{STAT}` is present and the
  17   invocation was successful, it is assigned the value 0. If it is present and the
  18   invocation has failed, it is assigned a positive value; in particular, for a
  19   coindexed :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value
  20   of ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image
  21   has failed, the value ``STAT_FAILED_IMAGE``.
  22
  23   :param VALUE:
  24     Scalar of the same type as :samp:`{ATOM}`. If the kind
  25     is different, the value is converted to the kind of :samp:`{ATOM}`.
  26
  27   :param ATOM:
  28     Scalar coarray or coindexed variable of either integer
  29     type with ``ATOMIC_INT_KIND`` kind or logical type with
  30     ``ATOMIC_LOGICAL_KIND`` kind.
  31
  32   :param STAT:
  33     (optional) Scalar default-kind integer variable.
  34
  35   Standard:
  36     Fortran 2008 and later; with :samp:`{STAT}`, TS 18508 or later
  37
  38   Class:
  39     Atomic subroutine
  40
  41   Syntax:
  42     .. code-block:: fortran
  43
  44       CALL ATOMIC_REF(VALUE, ATOM [, STAT])
  45
  46   Example:
  47     .. code-block:: fortran
  48
  49       program atomic
  50         use iso_fortran_env
  51         logical(atomic_logical_kind) :: atom[*]
  52         logical :: val
  53         call atomic_ref (atom, .false.)
  54         ! ...
  55         call atomic_ref (atom, val)
  56         if (val) then
  57           print *, "Obtained"
  58         end if
  59       end program atomic
  60
  61   See also:
  62     :ref:`ATOMIC_DEFINE`,
  63     :ref:`ATOMIC_CAS`,
  64     :ref:`ISO_FORTRAN_ENV`,
  65     :ref:`ATOMIC_FETCH_ADD`,
  66     :ref:`ATOMIC_FETCH_AND`,
  67     :ref:`ATOMIC_FETCH_OR`,
  68     :ref:`ATOMIC_FETCH_XOR`