To: J3 J3/14-151r1 From: John Reid and Reinhold Bader Subject: Coarray intrinsics Date: 2014 June 23 References: N2007, N2013 Discussion ---------- We currently have two ways to identify an ancestor team, TEAM and DISTANCE. We use TEAM in an image selector, e.g., A[TEAM :: i,j], in SYNC_IMAGES, and in FAILED_IMAGES. We use DISTANCE in TEAM_ID, NUM_IMAGES, and THIS_IMAGE. The intrinsic GET_TEAM provides conversion to TEAM. There is no conversion to DISTANCE, though it would be easy to extend TEAM_DEPTH to do this. DISTANCE is intrinsically unsafe because an ancestor team may be at different team distances on executing images of different teams. We think that TEAM should be used in TEAM_ID, NUM_IMAGES, and THIS_IMAGE. This makes TEAM_DEPTH redundant. GET_TEAM with the argument DISTANCE absent plays the useful role of providing a team variable for the current team and there are examples illustrating this. Beyond that, we believe GET_TEAM should support the most relevant cases of supplying the parent team and the initial team; alternatively, if a team variable appears in an image selector for a dummy coarray, it can be made available as another argument or by use or host association. We therefore propose the replacement of the optional argument DISTANCE in GET_TEAM by LEVEL with three possible integer values in ISO_FORTRAN_ENV: INITIAL_TEAM, PARENT_TEAM, CURRENT_TEAM. These changes mean that team depth will be removed entirely from the syntax. It remains a useful concept in the text. From the addition of sibling team addressing via the TEAM_ID keyword (5.4), it follows that some intrinsic support is needed for reliably obtaining results from IMAGE_INDEX and NUM_IMAGES when such addressing occurs. It seems best to provide three overloaded versions, one with an argument TEAM, one with an argument TEAM_ID, and one without either of these. In his vote (see N2013), Van Snyder says "Since TEAM_TYPE is not prohibited in a variable definition context, GET_TEAM could be a function instead of a subroutine. This would be handy for passing team variables as actual arguments." This paper also contains edits to implement this. Edits to N2007: --------------- [9:30+] Add paragraph "The integer constants INITIAL_TEAM, PARENT_TEAM, and CURRENT_TEAM are used to specify a team to the intrinsic function GET_TEAM. They are defined in in the intrinsic module ISO_FORTRAN_ENV." [11:12+] In note 5.2, change the line involving GET_TEAM to INITIAL = GET_TEAM() [17:5] Delete "TEAM_DEPTH,". [17:9] Before "MOVE_ALLOC", insert "IMAGE_INDEX, " [24:20-31] Replace by "<7.4.13 GET_TEAM([LEVEL])> Team value. Transformational function. LEVEL (optional) shall be a scalar with one of the values INITIAL_TEAM, PARENT_TEAM, and CURRENT_TEAM defined in the ISO_FORTRAN_ENV intrinsic module. It is an INTENT(IN) argument. Scalar and of type TEAM TYPE defined in the ISO_FORTRAN_ENV intrinsic module. The result is the value of a team variable of the current team if LEVEL is not present, LEVEL is present with the value CURRENT_TEAM, or the current team is the initial team. Otherwise, the result is the value of a team variable of the parent team if LEVEL is present with the value PARENT_TEAM, and of the initial team if LEVEL is present with the value INITIAL_TEAM." [24:37] Change line to WORLD_TEAM = GET_TEAM() [25:9] Change line to PARENT_TEAM = GET_TEAM() [25:21 to 25:38] Delete subclause 7.4.14. [25:40] Replace "DISTANCE" by "TEAM". [25:43] Replace line by TEAM (optional) shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. Its value shall represent an ancestor team. [26:2-6] Replace paragraph by <> If TEAM is present, the result has the value of the team identifier of the invoking image in the team specified by the value of TEAM; otherwise, the result value is the team identifier of the invoking image in the current team. [26:20+] Insert "7.5.1- IMAGE_INDEX The description of the intrinsic function IMAGE_INDEX in ISO/IEC 1539-1:2010 is changed by adding two overloaded additional versions that specify the team with the argument TEAM or the argument TEAM_ID, and a modified result if either of these versions is invoked. The TEAM argument shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. Its value shall represent an ancestor team. The TEAM_ID argument shall be a nonnegative scalar integer. Its value shall be that of a team identifier for one of the teams that were formed by the execution of a FORM TEAM statement for the current team." [27:6-7] Replace "two optional arguments ... present." by "the optional argument FAILED and two overloaded additional versions that specify the team with the argument TEAM or the argument TEAM_ID, and a modified result if any of these versions is invoked.". [27:8-11] Replace paragraph by The TEAM argument shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. Its value shall represent an ancestor team. The TEAM_ID argument shall be a nonnegative scalar integer. Its value shall be that of a team identifier for one of the teams that were formed by the execution of a FORM TEAM statement for the current team. [27:17] Replace "DISTANCE" by "TEAM" twice. [27:18-22] Replace paragraph by The TEAM argument shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. If TEAM is present, the result is the image index that the invoking image has in the team specified by the value of TEAM; otherwise, the result value is the image index of the invoking image in the current team. [34:14+] Change the entry for GET_TEAM to GET_TEAM ([LEVEL]) T Team value. [34:14+] Delete the table entry for TEAM_DEPTH, and in the table entry for TEAM_ID, delete "[,DISTANCE]". [34:16+] Add new entry "IMAGE_INDEX T (COARRAY, SUB) or (COARRAY, SUB, TEAM) or (COARRAY, SUB, TEAM_ID)" T I T Convert cosubscripts to image index" [34:18] Replace "([DISTANCE, FAILED])" by "{\ul ([FAILED]) or (TEAM[, FAILED]) or (TEAM_ID[, FAILED]) }" [34:19] Replace "DISTANCE" by "TEAM". [34:19+] Add THIS_IMAGE (COARRAY {\ul [,TEAM]) or} T Cosubscript(s) for this image {\ul (COARRAY, DIM [,TEAM]) } [35:2+] Insert "{In 13.7.79 IMAGE_INDEX, edit the subclause title as follows} 13.7.79 IMAGE_INDEX (COARRAY, SUB) {\ul or IMAGE_INDEX (COARRAY, SUB, TEAM) or IMAGE_INDEX (COARRAY, SUB, TEAM_ID)} {In 13.7.79 IMAGE_INDEX, edit the COARRAY argument description as follows} COARRAY shall be a coarray of any type. If the intrinsic is invoked with a TEAM_ID argument, it shall be established in an ancestor of the specified team. Otherwise, it shall be established in the specified team. {In 13.7.79 IMAGE_INDEX, add the arguments descriptions as follows} TEAM shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. It is an INTENT(IN) argument. Its value shall represent an ancestor team. TEAM_ID shall be a nonnegative scalar integer. It is an INTENT(IN) argument. Its value shall be that of a team identifier for one of the teams that were formed by the execution of a FORM TEAM statement for the current team. If TEAM or TEAM_ID is present, it specifies the team. Otherwise, the team specified is the current team. {In 13.7.79 IMAGE_INDEX, replace paragraph 5 with} <> If the value of SUB is a valid sequence of cosubscripts for COARRAY in the specified team, the result is the index of the corresponding image in that team. Otherwise, the result is zero." [35:12] Replace "NUM_IMAGES ([DISTANCE, FAILED])" by "NUM_IMAGES {\ul ([FAILED]) or NUM_IMAGES (TEAM[, FAILED]) or NUM_IMAGES (TEAM_ID[, FAILED]) }" [35:15] Replace line by TEAM shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. It is an INTENT(IN) argument. Its value shall represent an ancestor team. TEAM_ID shall be a nonnegative scalar integer. Its value shall be that of a team identifier for one of the teams that were formed by the execution of a FORM TEAM statement for the current team. [35:20-23] Replace paragraph by If TEAM or TEAM_ID is present, it specifies the team. Otherwise, the team specified is the current team. [35:28] Replace "DISTANCE" by "TEAM". [35:31] Replace line by TEAM (optional) shall be a scalar of the type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. Its value shall represent an ancestor team. If COARRAY appears, it shall be established for TEAM. [35:32] Change "replace ... with" by "at the end of paragraph 5 add", [35:33 to 36:1] Replace lines by Case (iv): The result of THIS_IMAGE (TEAM) is a scalar with a value equal to the index of the invoking image in the team specified by the value of TEAM. Case (v): The result of THIS_IMAGE (COARRAY, TEAM) is the sequence of cosubscript values for COARRAY that would specify the invoking image in the team specified by the value of TEAM. Case (vi): The result of THIS_IMAGE (COARRAY, DIM, TEAM) is the value of cosubscript DIM in the sequence of cosubscript values for COARRAY that would specify the invoking image in the team specified by the value of TEAM. [36:11] Change "final sentence of the first paragraph" to "final sentences of the first and final paragraphs".