To: J3 J3/14-151r3 From: John Reid and Reinhold Bader Subject: Coarray intrinsics Date: 2014 June 25 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: --------------- [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 integer whose value shall be equal to one of the named constants INITIAL_TEAM, PARENT_TEAM, and CURRENT_TEAM defined in the ISO_FORTRAN_ENV intrinsic module. Scalar and of type TEAM_TYPE defined in the ISO_FORTRAN_ENV intrinsic module. The result is the value of a team variable for 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 for the parent team if LEVEL is present with the value PARENT_TEAM, and for 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:39] 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 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 positive scalar integer. Its value shall be that of a team identifier for a team that was formed by 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 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 positive scalar integer. Its value shall be that of a team identifier for a team that was 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 function 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. Its value shall represent an ancestor team. TEAM_ID shall be a positive scalar integer. Its value shall be that of a team identifier for a team that was formed by execution of a FORM TEAM statement for the current team. If TEAM or TEAM_ID appears, 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. Its value shall represent an ancestor team. TEAM_ID shall be a positive scalar integer. Its value shall be that of a team identifier for a team that was formed by execution of a FORM TEAM statement for the current team. [35:20-23] Replace paragraph by If TEAM or TEAM_ID appears, 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:4+] Add "{In 13.8.2 The ISO_FORTRAN_ENV intrinsic module, insert a new subclause} 13.8.2.7a CURRENT_TEAM The value of the default integer scalar constant CURRENT_TEAM identifies the current team in an invocation of the function GET_TEAM." [36:7+] Add "{In 13.8.2 The ISO_FORTRAN_ENV intrinsic module, insert a new subclause} 13.8.2.9a INITIAL_TEAM The value of the default integer scalar constant INITIAL_TEAM identifies the initial team in an invocation of the function GET_TEAM. {In 13.8.2 The ISO_FORTRAN_ENV intrinsic module, insert a new subclause} 13.8.2.19a PARENT_TEAM The value of the default integer scalar constant PARENT_TEAM identifies the parent team in an invocation of the function GET_TEAM." [36:11] Change "final sentence of the first paragraph" to "final sentences of the first and final paragraphs".