To: J3 J3/14-173 From: Reinhold Bader Subject: STAT for atomic subroutines Date: 2014 June 09 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 STAT_FAILED_IMAGE in the intrinsic module ISO_FORTRAN_ENV if a coindexed ATOM argument is determined to be located on a failed image; otherwise it is assigned the value zero. If the STAT argument is present in an invocation of an atomic subroutine and an error condition occurs, the argument 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 with a STAT argument for which the value STAT_FAILED_IMAGE is returned, it is indeterminate whether the atomic action has been performed. This is because an image may have failed while the memory location used for the atomic variable on that image remains available." [[ Perhaps the EVENT argument of EVENT_QUERY should be treated analogously.]] [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 arguments descriptions 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 arguments descriptions as follows} STAT (optional) shall be a scalar of type default integer. It is an INTENT(OUT) argument."