---

C Library Functions  - atomic_ref (3)

---

NAME

ATOMIC_REF(3) - [ATOMIC] Atomically retrieve the value in a variable

SYNOPSIS

call atomic_ref(value, atom [,stat] )

         subroutine atomic_ref(value,atom,stat)

          integer(atomic_int_kind),intent(in) :: value
          integer(atomic_int_kind)            :: atom[*]
          integer,intent(out),intent(out)     :: stat

CHARACTERISTICS

o	ATOM is a scalar coarray or coindexed variable of either integer type with atomic_int_kind kind or logical type with atomic_logical_kind kind.
o	VALUE is a scalar of the same type as ATOM. If the kind is different, the value is converted to the kind of ATOM.
o	STAT is a Scalar default-kind integer variable.

DESCRIPTION

ATOMIC_REF(VALUE, ATOM, STAT) atomically retrieves the value of ATOM and stores it in VALUE. This ensures a thread-safe read operation.

When STAT is present and the invocation was successful, it is assigned the value 0. If it is present and the invocation has failed, it is assigned a positive value; in particular, for a coindexed ATOM, if the remote image has stopped, it is assigned the value of iso_fortran_env’s STAT_STOPPED_IMAGE and if the remote image has failed, the value STAT_FAILED_IMAGE.

Use for safe reading of shared variables in parallel contexts.

It complements ATOMIC_DEFINE for read-write operations.

OPTIONS

o	VALUE : Receives the value of ATOM. : Scalar of the same type as ATOM. If the kind is different, the value is converted to the kind of ATOM.
o	ATOM : Scalar coarray or coindexed variable of either integer type with ATOMIC_INT_KIND kind or logical type with ATOMIC_LOGICAL_KIND kind.
o	STAT : (optional) Scalar default-kind integer variable. Set to 0 on success, or a positive value on failure.

EXAMPLES

Sample program:

    program demo_atomic_ref
      use iso_fortran_env
      implicit none
      integer(atomic_int_kind) :: counter[*], value
      integer :: stat, me

      if (this_image() == 1) counter = 42
      sync all

      me = this_image()
      call atomic_ref(value, counter[1], stat)

      if (stat /= 0) then
        print *, "Image", me, ": Failed with STAT =", stat
      else
        print *, "Image", me, ": Retrieved value =", value
      end if
    end program demo_atomic_ref

Expected Output (4 images, order varies)

        > Image 1: Retrieved value = 42
        > Image 2: Retrieved value = 42
        > Image 3: Retrieved value = 42
        > Image 4: Retrieved value = 42

STANDARD

Fortran 2008 ; with STAT, TS 18508

SEE ALSO

ATOMIC_DEFINE(3), ATOMIC_CAS(3), ISO_FORTRAN_ENV(3),

ATOMIC_FETCH_ADD(3), ATOMIC_FETCH_AND(3),

ATOMIC_FETCH_OR(3), ATOMIC_FETCH_XOR(3)

See ISO_FORTRAN_ENV for constants like ATOMIC_INT_KIND, STAT_STOPPED_IMAGE, and STAT_FAILED_IMAGE.

Fortran intrinsic descriptions

---

Nemo Release 3.1

atomic_ref (3)

June 29, 2025

Generated by manServer 1.08 from 264d3b13-5de7-48f8-bd91-81d24a356d27 using man macros.