To: J3                                                     J3/24-164r3
From: generics
Subject: Edits for TEMPLATES: Instantiation
Date: 2024-October-29
References: 24-161, 24-162, 24-163, 24-125r5, 24-126r4, 24-127r4

Introduction:
=============

This is the 4th of 6 papers that provide edits for the approved syntax
for templates.

UTI: Can we enable I/O generic spec as an instantiation argument?

     instantiate foo(..., write(formatted))

Section 1:
==========

* Append the following at the end of clause 15 from paper 24-163.


15.6 Instantiation

15.6.1 The INSTANTIATE statement

An INSTANTIATE statement is a specification statement that identifies
an instance of a template by specifying instantiation arguments that
become associated with the deferred arguments of the named template.

R1524 <template-instantiate-stmt>
         <<is>> INSTANTIATE [::] <template-name> (
                [ <instantiation-arg-spec-list> ] ) [, <rename-list> ]
         <<or>> INSTANTIATE [::] <template-name> (
                [ <instantiation-arg-spec-list> ] ), ONLY : [ <only-list> ]

C1536 (R1524) The <template-name> shall be the name of a template that is
              not a templated procedure.

R1525 <templated-procedure-instantiate-stmt> <<is>>
          INSTANTIATE :: <local-name> => <template-name> (
          [ <instantiation-arg-spec-list> ] )

C1537 (R1525) The <template-name> shall be the name of a templated
              procedure.

R1526 <instantiate-stmt> <<is>> <template-instantiate-stmt>
                         <<or>> <template-procedure-instantiate-stmt>

C1538 (R1526) Within an <instantiate-stmt>, an <instantiation-arg> shall
              not depend on any entity defined within the referenced
              template.

C1539 (R1526) In <instantiate-stmt>, <template-name> shall not be the
              name of any construct in which it appears.

The INSTANTIATE statement without the ONLY option provides access to
all public entities of the referenced template.  The INSTANTIATE
statement with the ONLY option provides access only to those entities
that appear as <generic-specs>, <use-names>, or
<use-defined-operators> in the only list.

An accessible entity of the referenced instantiation is associated
with one or more accessed entities, each with its own identifier.
These identifiers are

   - the identifier of the entity in the referenced template if that
     identifier appears as an <only-use-name> or as the
     <defined-operator> of a <generic-spec> in any <only> for that
     instantiation,
   - each of the <local-names> or <local-defined-operators> that the
     entity is given in any <rename> for that instantiation, and

   - the identifier of the entity in that referenced template if
     that identifier does not appear as a <use-name> or
     <use-defined-operator> in any <rename> for that instantiation.


15.6.2 Inline instantiation of templated procedures

A templated procedure can be instantiated and referenced in
an expression or the <procedure-designator> in a <call-stmt>.

R1527 <inline-instantiate> <<is>>
    <template-name> ^ ( <instantiation-arg-spec-list> )

C1540 (R1527) The <template-name> shall be the name of a templated
              procedure.

C1541 (R1527) In <inline-instantiate>, <template-name> shall not be the
              name of any construct in which it appears.

The procedure designated by <inline-instantiate> is the procedure
produced from instantiating the templated procedure.

NOTE

    Templated procedures cannot reference themselves.


15.6.3 Interpretation of template instantiation

Multiple instantiations of a given template with the same actual
instantiation arguments identify the same instance of the referenced
template.

NOTE 1

    As a consequence, if a template defines a derived type, two
    identical instantiations of that template define the same type.
    This provides a mechanism for derived types from templates to be
    compatible across scoping units in a convenient manner. For
    example:

        TEMPLATE TMPL(T)
           DEFERRED TYPE :: T
           TYPE :: list_t
              TYPE(T), ALLOCATABLE :: elements(:)
           END TYPE
        END TEMPLATE

        ...

        SUBROUTINE SUB(list)
           INSTANTIATE TMPL(integer)
           TYPE(list_t) :: list
        END SUBROUTINE

        SUBROUTINE DRIVER()
           INSTANTIATE TMPL(integer)
           TYPE(list_t) :: list ! list_t is same type as in SUB
           CALL SUB(list)
        END SUBROUTINE

Two corresponding constant instantiation arguments are the same if and
only if both have the same shape, same type, same type parameters, and
are equal.

Two corresponding type-spec instantiation arguments are the same if
and only if both have the same type and have the same kind and length
type parameters.

Two corresponding procedure instantiation arguments are the same if
and only if both resolve to the same specific procedure.

NOTE 2

    Example showing how procedure instantiation arguments influence
    whether instantiations are the same:

        INTERFACE
           SUBROUTINE F1(x)
              TYPE(MY_T) :: x
           END SUBROUTINE
           SUBROUTINE F2(x)
              TYPE(MY_U) :: x
           END SUBROUTINE
           SUBROUTINE F3(x)
              TYPE(MY_U) :: x
           END SUBROUTINE
        END INTERFACE

        GENERIC :: A => F1, F2
        GENERIC :: B => F1, F3

        TEMPLATE TMPL(T, F)
            DEFERRED TYPE :: T
            DEFERRED INTERFACE
               SUBROUTINE F(x)
                  TYPE(T), INTENT(INOUT) :: x
               END SUBROUTINE F
            END INTERFACE
        END TEMPLATE

        INSTANTIATE TMPL(MY_T, A) ! Resolves to F1
        INSTANTIATE TMPL(MY_T, B) ! Resolves to F1 ==> same

        INSTANTIATE TMPL(MY_U, A) ! Resolves to F2
        INSTANTIATE TMPL(MY_U, B) ! Resolves to F3 ==> different


15.6.4 Deferred argument association

15.6.4.1 Instantiation arguments

Instantiation arguments are specified by an INSTANTIATE statement, a
REQUIRE statement, or by inline instantiation.

R1528 <instantiation-arg-spec> <<is>>
          [ <keyword> = ] <instantiation-arg>

C1542 (R1528) Each <keyword> shall be the name of a deferred argument in
              the referenced requirement or template.

In the absence of an argument keyword, an instantiation argument
corresponds to the deferred argument occupying the corresponding
position in <deferred-arg-list>; that is, the first instantiation
argument corresponds to the first deferred argument in the
reduced list, the second instantiation argument corresponds to the
second deferred argument in the reduced list, etc.

R1529 <instantiation-arg> <<is>> <constant-expr>
                          <<or>> <type-spec>
                          <<or>> <generic-spec>
                          <<or>> <procedure-name>

C1542b (R1529) The <generic-spec> shall not be
               <defined-io-generic-spec>.

{UTI:
      A defined I/O generic-spec cannot be used here because its
      syntax of "READ(FORMATTED)", (and etc.) conflicts with other syntax.
      E.g. that could be an array element reference, or a function
      reference. We either need to say that defined I/O generics are not
      permitted, provide separate syntax for it, or say that an
      instantiation arg that is for a deferred procedure has special
      behavior in that the READ(FORMATTED), etc., will always refer to
      the defined I/O, not anything else it might possibly be.
}

15.6.4.2 Deferred type association

C1543 (R1529) An <instantiation-arg> that is a <type-spec> shall
              correspond to a deferred argument that is a deferred type
              in the referenced template or requirement.

C1544 (R1529) An <instantiation-arg> that is a <type-spec> shall have
              constant type parameters.

C1545 (R1529) An <instantiation-arg> that corresponds to a deferred type
              that does not have the ABSTRACT attribute shall not be
              abstract.

C1546 (R1529) An <instantiation-arg>, T, that corresponds to a deferred
              type shall be a type for which a variable whose declared
              type is T is permitted in a variable definition context.

NOTE 1
      Constraint C1545 ensures that intrinsic assignment is available for
      variables of deferred type.  However, the constraint disallows some
      types, e.g., the EVENT_TYPE, from being used as an instantiation
      argument.

C1547 (R1529) An <instantiation-arg> that corresponds to a deferred type
              that has the EXTENSIBLE attribute shall be an extensible
              derived type.

C1548 (R1529) An <instantiation-arg> that corresponds to a deferred
              type shall not have a coarray potential subobject
              component.

NOTE 2
      Constraint C1548 avoids the possibility of assignment
      being invalid where the variable and expr do not agree on
      the allocation status of a coarray component.

NOTE 3
      Non-abstract, extensible derived types can be associated with
      both abstract and non-extensible deferred type arguments.

NOTE 4
      Intrinsic types, SEQUENCE types, and types with the BIND attribute
      cannot be associated with deferred type arguments that have the
      EXTENSIBLE attribute.

      Simple example illustrating the above.

      TYPE :: MY_T1
      END TYPE

      TYPE, ABSTRACT :: MY_T2
      END TYPE

      TEMPLATE TMPL1(T)
         DEFERRED TYPE :: T
      END TEMPLATE TMPL

      TEMPLATE TMPL2(U)
         DEFERRED TYPE, ABSTRACT :: U
      END TEMPLATE TMPL

      INSTANTIATE TMPL1(INTEGER) ! ok
      INSTANTIATE TMPL1(MY_T1)   ! ok
      INSTANTIATE TMPL1(MY_T2)   ! invalid

      INSTANTIATE TMPL2(INTEGER) ! invalid
      INSTANTIATE TMPL2(MY_T1)   ! ok
      INSTANTIATE TMPL2(MY_T2)   ! ok

15.6.4.3 Deferred constant association

C1549 (R1529) The <constant-expr> shall be of type INTEGER, LOGICAL or
              CHARACTER.

C1550 (R1529) An <instantiation-arg> that is a <constant-expr> shall
              correspond to a deferred argument that is a deferred constant
              in the referenced template or requirement.

C1551 (R1529) The type and kind of an <instantiation-arg> that is a
              <constant-expr> shall have the same type and kind as the
              corresponding deferred constant in the referenced template
              or requirement.

C1552 (R1529) If the shape of the corresponding deferred constant in the
              referenced template or requirement is not implied, then
              the <constant-expr> shall have the same shape.

C1553 (R1529) If the rank of the corresponding deferred constant in the
              referenced template or requirement is not implied, then
              the <constant-expr> shall have the same rank.


15.6.4.4 Deferred procedure association

C1554 (R1529) An <instantiation-arg> that is a <generic-spec> or
              <procedure-name> shall correspond to a deferred argument that
              is a deferred procedure in the referenced template or
              requirement.

C1555 (R1529) An <instantiation-arg> that is a <procedure-name> shall
              have the same characteristics as the corresponding
              deferred procedure in the referenced template or
              requirement, except that a pure instantiation argument may
              be associated with a deferred argument that is not pure, a
              simple instantiation argument may be associated with a
              deferred argument that is not simple, and an elemental
              instantiation argument may be associated with a deferred
              procedure that is not elemental.

C1556 An <instantiation-arg> that is a <generic-spec> shall be a
      generic identifier with exactly one specific procedure that
      has the same characteristics as the corresponding deferred
      procedure of the referenced
      template or requirement, except that a pure instantiation
      argument may be associated with a deferred argument that
      is not pure, a simple instantiation argument may be
      associated with a deferred argument that is not simple,
      and an elemental instantiation argument may be associated
      with a deferred procedure that is not elemental.

The deferred procedure is associated with the specific procedure that is
consistent with the characteristics.

{UTI: This sentence is too vague. Perhaps this is better?
  If an instantation argument is a generic identifier, the corresponding
  deferred procedure is associated with the specific procedure of that
  generic identifier that is consistent with the characteristics of the
  deferred procedure.
We may also need to explicitly say what happens if the instantiation
argument is not a generic. And for that matter, say how association
happens for deferred constants and deferred types.}

===END===