To: J3 J3/14-173r1 From: Reinhold Bader & Nick Maclaren Subject: STAT for atomic subroutines Date: 2014 June 24 References: N2007, N2013 Discussion: ~~~~~~~~~~~ This paper suggests adding an optional STAT argument to the atomic subroutines to enable coping with image failure without requiring multiple statements that involve a race condition. Because the generic interface for many ATOMIC_ procedures would become potentially ambiguous, I suggest to separate the fetch-and-op variant from the regular op. EDITS to N2007: ~~~~~~~~~~~~~~~ [17:9] Before "MOVE_ALLOC", add "ATOMIC_DEFINE, ATOMIC_REF, " [17:19+] Add new paragraph "If the STAT argument is present in an invocation of an atomic subroutine and no error condition occurs, the argument is assigned the value zero. If the STAT argument is present in an invocation of an atomic subroutine and an error condition occurs, the ATOM argument becomes undefined, and the OLD argument becomes undefined if it is present. Argument STAT is assigned the value STAT_FAILED_IMAGE if a coindexed ATOM argument is determined to be located on a failed image, or the value STAT_STOPPED_IMAGE in the intrinsic module ISO_FORTRAN_ENV if a coindexed ATOM argument is determined to be located on a stopped image; otherwise, the argument is assigned a processor-dependent positive value that is different from STAT_STOPPED_IMAGE and STAT_FAILED_IMAGE. NOTE 7.1- If an atomic subroutine is executed for an object on a failed image, it is indeterminate whether the call will fail. This is because an image might fail, but the memory location used for the atomic variable on that image might remain available." [18:12] Replace "ATOMIC_ADD (ATOM, VALUE)" by "ATOMIC_ADD (ATOM, VALUE [,STAT])" and delete "or ATOMIC_ADD (ATOM, VALUE, OLD)" [18:21-22] Delete. [18:22+] Insert "STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [18:23] Replace "Examples." by "Example." [18:25-26] Delete paragraph. [18:26+] Add new subsection "7.4.1+ ATOMIC_FETCH_ADD (ATOM, VALUE, OLD [, STAT]) Description. Atomic fetch and add operation. Class. Atomic subroutine. Arguments. ATOM shall be a scalar coarray or coindexed object 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 of ATOM + INT(VALUE, ATOMIC_INT_KIND). VALUE shall be scalar and of type integer. It is an INTENT (IN) argument. OLD shall be a scalar and of the same type and kind as ATOM. It is an INTENT (OUT) argument. It is defined with the value of ATOM that was used for performing the add operation. STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument. Example. CALL ATOMIC_FETCH_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 is defined with the value 99 if the previous value of M was 99 on image 4." [18:27] Replace "ATOMIC_AND (ATOM, VALUE)" by "ATOMIC_AND (ATOM, VALUE [,STAT])" and delete "or ATOMIC_AND (ATOM, VALUE, OLD)" [19:7-8] Delete. [19:8+] Insert "STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [19:9-11] Delete ",IOLD" and "and the value of IOLD on the image executing the statement to be defined with the value 5". [19:11+] Add new subsection "7.4.2+ ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT]) Description. Atomic bitwise fetch and AND operation. Class. Atomic subroutine. Arguments. ATOM shall be a scalar coarray or coindexed object 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 a scalar and of the same type and kind as ATOM. It is an INTENT (OUT) argument. It is defined with the value of ATOM that was used for performing the bitwise AND operation. STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument. Example. CALL ATOMIC_FETCH_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 be defined with the value 5 if the value of I[3] was 5 when the bitwise fetch and AND operation executed." [19:12] After "NEW", insert "[,STAT]" [19:26+] Insert "STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [19:30] Replace "ATOMIC_OR (ATOM, VALUE)" by "ATOMIC_OR (ATOM, VALUE [,STAT])" and delete "or ATOMIC_OR (ATOM, VALUE, OLD)" [19:39-40] Delete. [19:40+] Insert "STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [19:41-43] Delete ",IOLD" and "and the value of IOLD on the image executing the statement to be defined with the value 2". [19:43+] Add new subsection "7.4.4+ ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT]) Description. Atomic bitwise fetch and OR operation. Class. Atomic subroutine. Arguments. ATOM shall be a scalar coarray or coindexed object 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 a scalar and of the same type and kind as ATOM. It is an INTENT (OUT) argument. It is defined with the value of ATOM that was used for performing the bitwise OR operation. STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument. Example. CALL ATOMIC_FETCH_OR (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 be defined with the value 2 if the value of I[3] was 2 when the bitwise OR operation executed." [20:1] Replace "ATOMIC_XOR (ATOM, VALUE)" by "ATOMIC_XOR (ATOM, VALUE [,STAT])" and delete "or ATOMIC_XOR (ATOM, VALUE, OLD)" [20:10-11] Delete. [20:11+] Insert "STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [20:12-14] Delete ",IOLD" and "and the value of IOLD on the image executing the statement to be defined with the value 3". [20:14+] Add new subsection "7.4.5+ ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [,STAT]) Description. Atomic bitwise fetch and exclusive OR operation. Class. Atomic subroutine. Arguments. ATOM shall be a scalar coarray or coindexed object 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 a scalar and of the same type and kind as ATOM. It is an INTENT (OUT) argument. It is defined with the value of ATOM that was used for performing the bitwise exclusive OR operation. Example. CALL ATOMIC_FETCH_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 be defined with the value 3 if the value of I[3] was 3 when the bitwise exclusive OR operation executed. [26:20+] Add new subsection "7.5.1- ATOMIC_DEFINE, ATOMIC_REF The descriptions of the intrinsic functions ATOMIC_DEFINE and ATOMIC_REF in ISO/IEC 1539-1:2010 are changed to take account of the possibility that an ATOM argument is located on a failed image. STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument." [34:14] Edit table as follows: for ATOMIC_[op=ADD,AND,OR,XOR]: (1) replace "(ATOM, VALUE)" by "ATOM, VALUE [,STAT]) and delete "or (ATOM, VALUE, OLD)" (2) add a new entry "ATOMIC_FETCH_ I (ATOM, VALUE, OLD [,STAT]) I A I Atomic fetch and operation" [34:15] After "entries for", add "ATOMIC_DEFINE, ATOMIC_REF," [34:16+] Add table entries "ATOMIC_DEFINE I (ATOM, VALUE \underwave{[,STAT]}) I A I Define a variable atomically. ATOMIC_REF I (VALUE, ATOM, \underwave{[,STAT]}) I A I Reference a variable atomically." [35:2+] Add "{In 13.7.20 ATOMIC_DEFINE, edit the subclause title as follows} 13.7.20 ATOMIC_DEFINE (ATOM, VALUE \underwave{[,STAT]}) {In 13.7.20 ATOMIC_DEFINE, add the argument description as follows} STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument. {In 13.7.21 ATOMIC_REF, edit the subclause title as follows} 13.7.21 ATOMIC_REF (VALUE, ATOM \underwave{[,STAT]}) {In 13.7.21 ATOMIC_REF, add the argument description as follows} STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument. Add the extra paragraph If an error condition occurs, the VALUE argument becomes undefined."