To: J3 12-167r3 From: Bill Long Subject: Atomic subroutines Date: 2012 June 29 Discussion: --------- N1930 requirement 4 adds five new atomic subroutines to the Coarray TS. This paper provides semantics and edits for these routines. Semantics: ---------- The operation of the atomic add intrinsic: atomic_add (atom, value, old) is to perform atomically: if (present (old) ) old = atom atom = atom + value The operation of the bitwise AND intrinsic atomic_and (atom, value, old) is to perform atomically: if (present(old)) old = atom atom = iand(atom,INT(value,ATOMIC_INT_KIND)) The operation of the compare and swap intrinsic atomic_cas (atom, old, compare, new) is to perform atomically: old = atom if (old == compare) atom = new The operation of the bitwise OR intrinsic atomic_or (atom, value, old) is to perform atomically: if (present(old)) old = atom atom = ior(atom,INT(value,ATOMIC_INT_KIND)) The operation of the bitwise exclusive OR intrinsic atomic_xor (atom, value, old) is to perform atomically: if (present(old)) old = atom atom = ieor(atom,INT(value,ATOMIC_INT_KIND)) Edits: --------- Insert these subclauses in Clause 7 of the TS: "7.1 General Detailed specifications of the generic intrinsic collective subroutines CO_BCAST, CO_MAX, CO_MIN, CO_REDUCE, and CO_SUM are provided in 7.2. Detailed specifications of the the generic intrinsic atomic subroutines ATOMIC_ADD, ATOMIC_AND, ATOMIC_CAS, ATOMIC_OR, and ATOMIC_XOR are provided in 7.3. The types and type parameters of the arguments to these intrinsic subroutines are determined by these specifications. The "Argument" paragraphs specify requirements on the actual arguments of the procedures. All of these intrinsics are pure. 7.3 New atomic subroutines 7.3.1 ATOMIC_ADD (ATOM, VALUE [, OLD]) Description. Atomic add operation. Class. Atomic subroutine. Arguments. ATOM shall be scalar and of type integer with kind ATOMIC_INT_KIND, where ATOMIC_INT_KIND is the named constant in the intrinsic module ISO_FORTRAN_ENV. It is an INTENT (INOUT) argument. ATOM becomes defined with the value of ATOM + VALUE. VALUE shall be scalar and of type integer. It is an INTENT (IN) argument. OLD (optional) shall be scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of ATOM that was used for performing the ADD operation. Example1. CALL ATOMIC_ADD(I[3], 42) causes the value of I on image 3 to have its to become its previous value plus 42. Example2. CALL ATOMIC_ADD(M[4], N, ORIG) causes the value of M on image 4 to become its previous value plus the value of N on this image. ORIG becomes defined with 99 if the previous value of M was 99 on image 4. 7.3.2 ATOMIC_AND (ATOM, VALUE [, OLD]) Description. Atomic bitwise AND operation 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 (optional) shall be scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of ATOM that was used for performing the bitwise AND operation. Example. CALL ATOMIC_AND (I[3], 6, Iold) causes I on image 3 to become defined with the value 4 and the value of Iold on the image executing the statement to become defined with the value 5 if the value of I[3] was 5 when the bitwise AND operation executed. 7.3.3 ATOMIC_CAS (ATOM, OLD, COMPARE, NEW) Description. Atomic compare and swap. 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 ATOM that was used for performing 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." 7.3.4 ATOMIC_OR (ATOM, VALUE [, OLD]) Description. Atomic bitwise OR operation. 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 (optional) shall be scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of ATOM that was used for performing the bitwise OR operation. Example. CALL ATOMIC_XOR (I[3], 1, Iold) causes I on image 3 to become defined with the value 3 and the value of Iold on the image executing the statement to become defined with the value 2 if the value of I[3] was 2 when the bitwise OR operation executed. 7.3.5 ATOMIC_XOR (ATOM, VALUE [, OLD]) Description. Atomic bitwise exclusive OR operation. 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 (optional) shall be scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of ATOM that was used for performing the bitwise exclusive OR operation. Example. CALL ATOMIC_XOR (I[3], 1, Iold) causes I on image 3 to become defined with the value 2 and the value of Iold on the image executing the statement to become defined with the value 3 if the value of I[3] was 3 when the bitwise exclusive XOR operation executed." --------------------------- In the Edits clause of the TS, in the subclause for edits to Clause 13, add '[323:Table13.1] In Table 13.1 Standard generic intrinsic procedure summary, add a new entries "ATOMIC_ADD (ATOM, VALUE [,OLD]) A Atomic ADD operation. ATOMIC_AND (ATOM, VALUE [,OLD]) A Atomic bitwise AND operation. ATOMIC_CAS (ATOM, OLD, COMPARE, NEW) A Atomic compare and swap. ATOMIC_OR (ATOM, VALUE [,OLD]) A Atomic bitwise OR operation. ATOMIC_XOR (ATOM, VALUE [,OLD]) A Atomic bitwise exclusive OR operation. --------------------------- In the Edits clause of the TS, in the subclause for edits to Clause 13, add "Move subclauses 7.3.1 through 7.3.5 in this Technical Specification to Subclause 13.7 of \Fortranstandard{} in order alphabetically." ---------------------------