To: J3 11-200r1 From: Bill Long Subject: Atomic intrinsics - Coarray TR Date: 13 June 2011 Reference: WG5/N1835, 11-176, 09-184 Discussion: ----------- Several people external to WG5, and several members of the committee, have proposed that in addition to ATOMIC_DEFINE and ATOMIC_REF it is very useful to add an atomic read-modify-write intrinsic. The most basic of those in both theoretical works and also practical implementations is the atomic compare-and-swap (CAS) intrinsic. The basic operation of this intrinsic is: atomic_cas (atom, old, compare, new) which performs atomically: old = atom if (old == compare) atom = new Paper 09-184 had proposed adding an atomic compare and swap routine. At the time, it was decided to defer that feature to the Coarray TR. The following further atomic subroutines are suggested: atomic_add atomic_fadd atomic_and atomic_fand atomic_or atomic_for atomic_xor atomic_fxor where the 'f' versions are the "fetch_and_" versions of the ones with out the 'f'. These have existed (with different spelling) in the Cray coarray implementation from the beginning due to specific customer demands. All take integer arguments. Having standardized and portable names would be good. Edits to 11-176: ---------------- [9:17+] In 4.2 Standard generic intrinsic procedures, add a new line for the A Class column identifier, aligned with the text in [9:18]: " A indicates that the procedure is an atomic subroutine," [9:19+] Add 9 entries to Table 4.1, alphabetically: "ATOMIC_ADD (ATOM, VALUE) A Add values atomically. ATOMIC_AND (ATOM, VALUE) A Bitwise AND values atomically. ATOMIC_CAS (ATOM, OLD, A Conditionally swap values COMPARE, NEW) atomically. ATOMIC_FADD (ATOM, VALUE, OLD) A Add values atomically, with fetch. ATOMIC_FAND (ATOM, VALUE, OLD) A Bitwise AND values atomically, with fetch. ATOMIC_FOR (ATOM, VALUE, OLD) A Bitwise OR values atomically, with fetch. ATOMIC_FXOR (ATOM, VALUE, OLD) A Bitwise exclusive OR values atomically, with fetch. ATOMIC_OR (ATOM, VALUE) A Bitwise OR values atomically. ATOMIC_XOR (ATOM, VALUE) A Bitwise exclusive OR values atomically." [10:1+] At the beginning of 4.3 Specifications of the standard intrinsic procedures, add these new subclauses: "4.3.Xa ATOMIC_ADD (ATOM, VALUE) Description. Add values atomically. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value ATOM + VALUE. VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. Example. CALL ATOMIC_ADD (I[3], 1) causes I on image 3 to become defined with the value I + 1. 4.3.Xb ATOMIC_AND (ATOM, VALUE) Description. Bitwise AND values atomically. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IAND(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. Example. CALL ATOMIC_AND (I[3], 1) causes I on image 3 to become defined with the value IAND(I,1). 4.3.Xc ATOMIC_CAS (ATOM, OLD, COMPARE, NEW) Description. Conditionally swap values atomically. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND or of type logical with kind ATOMIC_LOGICAL_KIND, where ATOMIC_INT_KIND and ATOMIC_LOGICAL_KIND are the named constants in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT (INOUT) argument. If the value of ATOM is equal to the value of COMPARE, ATOM becomes defined with the value of INT (NEW, ATOMIC_INT_KIND) if it is of type integer, and with the value of NEW if it of type logical. OLD shall be scalar and of the same type as ATOM. It is an INTENT (OUT) argument. It becomes defined with the value of INT (ATOMC, KIND (OLD)) if ATOM is of type integer, and the value of ATOMC if ATOM is of type logical, where ATOMC has the same type and KIND as ATOM and has the value of ATOM used for the compare operation. COMPARE shall be scalar and of the same type and kind as ATOM. It is an INTENT(IN) argument. NEW shall be scalar and of the same type as ATOM. It is an INTENT(IN) argument. Example. CALL ATOMIC_CAS(I[3], OLD, Z, 1) causes I on image 3 to become defined with the value 1 if its value is that of Z, and OLD to become defined with the value of I on image 3 prior to the comparison." 4.3.Xd ATOMIC_FADD (ATOM, VALUE, OLD) Description. Add values atomically, with fetch. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value ATOM + VALUE. VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. OLD shall be scalar of the same type and kind as ATOM. It is an INTENT(OUT) argument. OLD becomes define with the value of ATOM that was added to VALUE to produce the result ATOM value. Example. CALL ATOMIC_ADD (I[3], 1, Iold) causes I on image 3 to become defined with the value 4 and the Iold to become defined with the value 3 if the value of I[3] was 3 when the addition operation executed. 4.3.Xe ATOMIC_FAND (ATOM, VALUE, OLD) Description. Bitwise AND values atomically, with fetch. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IAND(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. OLD shall be scalar of the same type and kind as ATOM. It is an INTENT(OUT) argument. OLD becomes define with the value of ATOM that was bitwise anded with VALUE to produce the result ATOM value. Example. CALL ATOMIC_FAND (I[3], 1, Iold) causes I on image 3 to become defined with the value 1 and the value of Iold to become defined with the value 3 if the value of I[3] was 3 when the bitwise AND operation executed. 4.3.Xf ATOMIC_FOR (ATOM, VALUE, OLD) Description. Bitwise OR values atomically, with fetch. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IOR(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. OLD shall be scalar of the same type and kind as ATOM. It is an INTENT(OUT) argument. OLD becomes define with the value of ATOM that was bitwise ored with VALUE to produce the result ATOM value. Example. CALL ATOMIC_FOR (I[3], 1, Iold) causes I on image 3 to become defined with the value 3 and the value of Iold to become defined with the value 2 if the value of I[3] was 2 when the bitwise OR operation executed. 4.3.Xg ATOMIC_FXOR (ATOM, VALUE, OLD) Description. Bitwise exclusive OR values atomically, with fetch. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IEOR(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. OLD shall be scalar of the same type and kind as ATOM. It is an INTENT(OUT) argument. OLD becomes define with the value of ATOM that was bitwise exclusive ored with VALUE to produce the result ATOM value. Example. CALL ATOMIC_FXOR (I[3], 1, Iold) causes I on image 3 to become defined with the value 2 and the value of Iold to become defined with the value 3 if the value of I[3] was 3 when the bitwise exclusive OR operation executed. 4.3.Xh ATOMIC_OR (ATOM, VALUE) Description. Bitwise OR values atomically. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IOR(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. Example. CALL ATOMIC_FOR (I[3], 1) causes I on image 3 to become defined with the value 3 if the value of I[3] was 2 when the bitwise OR operation executed. 4.3.Xi ATOMIC_XOR (ATOM, VALUE) Description. Bitwise exclusive OR values atomically. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is a named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT(INOUT) argument. ATOM becomes defined with the value IEOR(ATOM, INT(VALUE,ATOMIC_INT_KIND)). VALUE shall be scalar and of type integer. It is an INTENT(IN) argument. Example. CALL ATOMIC_FXOR (I[3], 1) causes I on image 3 to become defined with the value 2 if the value of I[3] was 3 when the bitwise exclusive OR operation executed."