To: J3 12-167r1 From: Bill Long Subject: Atomic compare-and-swap Date: 2012 June 27 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 specification of the generic intrinsic collective subroutines CO_BCAST, CO_MAX, CO_MIN, CO_REDUCE, and CO_SUM are provided in 7.2. Detailed specification 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 this specification. The “Argument” paragraphs specify requirements on the actual arguments of the procedure. All of these intrinsics are pure. 7.3 New atomic subroutines 7.3.1 ATOMIC_ADD (ATOM, VALUE [, OLD]) Description. Atomically perform an 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 an scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of INT(ATOMC, KIND (OLD)), where ATOMC has the value of ATOM used for the performing the add operation. Example1. CALL ATOMIC_ADD(I[3], 42) causes I on image 3 to have its value replaced with its original value plus 42. Example2. CALL ATOMIC_ADD(M[4], N, ORIG) causes M on image 4 to have its value replaced with its original value plus the value of N on this image. ORIG becomes defined with 99 if the original value of M as 99 on image 4." 7.3.2 ATOMIC_AND (ATOM, VAULE [, OLD]) Description. Perform atomic bitwise AND, optionally after fetching the input value of ATOM. 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 an scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of INT(ATOMC, KIND (OLD)), where ATOMC has the value of ATOM used for the 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. 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." 7.3.4 ATOMIC_OR (ATOM, VALUE [, OLD]) Description. Perform atomic bitwise OR, optionally after fetching the input value of ATOM. 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 an scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of INT(ATOMC, KIND (OLD)), where ATOMC has the value of ATOM used for the 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. Perform atomic bitwise exclusive OR, optionally after fetching the input value of ATOM. 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 an scalar of the same type as ATOM. It is an INTENT (OUT) argument. If it is present, it becomes defined with the value of INT(ATOMC, KIND (OLD)), where ATOMC has the value of ATOM used for the 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 Perform an atomic ADD operation. ATOMIC_AND (ATOM, VALUE [,OLD]) A Perform a bitwise AND atomic update operation after an optional fetch. ATOMIC_CAS (ATOM, OLD, COMPARE, NEW) A Conditionally swap values atomically. ATOMIC_OR (ATOM, VALUE [,OLD]) A Perform a bitwise OR atomic update operation after an optional fetch. ATOMIC_XOR (ATOM, VALUE [,OLD]) A Perform a bitwise exclusive OR atomic update operation after an optional fetch. "' --------------------------- 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." ---------------------------