flang/docs/RuntimeTypeInfo.md

   1 <!--===- docs/RuntimeTypeInfo.md
   2
   3    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4    See https://llvm.org/LICENSE.txt for license information.
   5    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6
   7 -->
   8
   9 # The derived type runtime information table
  10
  11 ```eval_rst
  12 .. contents::
  13    :local:
  14 ```
  15
  16 ## Overview
  17
  18 Many operations on derived types must be implemented, or can be
  19 implemented, with calls to the runtime support library rather than
  20 directly with generated code.
  21 Some operations might be initially implemented in the runtime library
  22 and then reimplemented later in generated code for compelling
  23 performance gains in optimized compilations.
  24
  25 The runtime library uses *derived type description* tables to represent
  26 the relevant characteristics of derived types.
  27 This note summarizes the requirements for these descriptions.
  28
  29 The semantics phase of the F18 frontend constructs derived type
  30 descriptions from its scoped symbol table after name resolution
  31 and semantic constraint checking have succeeded.
  32 The lowering phase then transfers the tables to the static
  33 read-only data section of the generated program by translating them into
  34 initialized objects.
  35 During execution, references to the tables occur by passing their addresses
  36 as arguments to relevant runtime library APIs and as pointers in
  37 the addenda of descriptors.
  38
  39 ## Requirements
  40
  41 The following Fortran language features require, or may require, the use of
  42 derived type descriptions in the runtime library.
  43
  44 ### Components
  45
  46 The components of a derived type need to be described in component
  47 order (7.4.7), but when there is a parent component, its components
  48 can be described by reference to the description of the type of the
  49 parent component.
  50
  51 The ordered component descriptions are needed to implement
  52 * default initialization
  53 * `ALLOCATE`, with and without `SOURCE=`
  54 * intrinsic assignment of derived types with `ALLOCATABLE` and
  55   automatic components
  56 * intrinsic I/O of derived type instances
  57 * `NAMELIST` I/O of derived type instances
  58 * "same type" tests
  59
  60 The characteristics of data components include their names, types,
  61 offsets, bounds, cobounds, derived type descriptions when appropriate,
  62 default component initializers, and flags for `ALLOCATABLE`, `POINTER`,
  63 `PRIVATE`, and automatic components (implicit allocatables).
  64 Procedure pointer components require only their offsets and address(es).
  65
  66 ### Calls to type-bound procedures
  67
  68 Only extensible derived types -- those without `SEQUENCE` or `BIND(C)`
  69 -- are allowed to have type-bound procedures.
  70 Calls to these bindings will be resolved at compilation time when
  71 the binding is `NON_OVERRIDABLE` or when an object is not polymorphic.
  72 Calls to overridable bindings of polymorphic objects requires the
  73 use of a runtime table of procedure addresses.
  74
  75 Each derived type (or instantiation of a parameterized derived type)
  76 will have a complete type-bound procedure table in which all of the
  77 bindings of its ancestor types appear first.
  78 (Specifically, the table offsets of any inherited bindings must be
  79 the same as they are in the table of the ancestral type's table.)
  80 These ancestral bindings reflect their overrides, if any.
  81
  82 The non-inherited bindings of a type then follow the inherited
  83 bindings, and they do so in alphabetical order of binding name.
  84 (This is an arbitrary choice -- we could also define them to
  85 appear in binding declaration order, I suppose -- but a consistent
  86 ordering should be used so that relocatables generated by distinct
  87 versions of the F18 compiler will have a better chance to interoperate.)
  88
  89 ### Type parameter values and "same type" testing
  90
  91 The values of the `KIND` and `LEN` parameters of a particular derived type
  92 instance can be obtained to implement type parameter inquiries without
  93 requiring derived type information tables.
  94 In the case of a `KIND` type parameter, it's a constant value known at
  95 compilation time, and in the case of a `LEN` type parameter, it's a
  96 member of the addendum to the object's descriptor.
  97
  98 The runtime library will have an API (TBD) to be called as
  99 part of the implementation of `TYPE IS` and `CLASS IS` guards
 100 of the `SELECT TYPE` construct.
 101 This language support predicate returns a true result when
 102 an object's type matches a particular type specification and
 103 `KIND` (but not `LEN`) type parameter values.
 104
 105 Note that this "is same type as" predicate is *not* the same as
 106 the one to be called to implement the `SAME_TYPE_AS()` intrinsic function,
 107 which is specified so as to *ignore* the values of `KIND` type
 108 parameters.
 109
 110 Subclause 7.5.2 defines what being the "same" derived type means
 111 in Fortran.
 112 In short, each definition of a derived type defines a distinct type,
 113 so type equality testing can usually compare addresses of derived
 114 type descriptions at runtime.
 115 The exceptions are `SEQUENCE` types and interoperable (`BIND(C)`)
 116 types.
 117 Independent definitions of each of these are considered to be the "same type"
 118 when these definitions match in terms of names, types, and attributes,
 119 both being either `SEQUENCE` or `BIND(C)`, and containing
 120 no `PRIVATE` components.
 121 These "sequence" derived types cannot have type parameters, type-bound
 122 procedures, an absence of components, or components that are not themselves
 123 of a sequence type, so we can use a static hash code to implement
 124 their "same type" tests.
 125
 126 ### FINAL subroutines
 127
 128 When an instance of a derived type is deallocated or goes out of scope,
 129 one of its `FINAL` subroutines may be called.
 130 Subclause 7.5.6.3 defines when finalization occurs -- it doesn't happen
 131 in all situations.
 132
 133 The subroutines named in a derived type's `FINAL` statements are not
 134 bindings, so their arguments are not passed object dummy arguments and
 135 do not have to satisfy the constraints of a passed object.
 136 Specifically, they can be arrays, and cannot be polymorphic.
 137 If a `FINAL` subroutine's dummy argument is an array, it may be
 138 assumed-shape or assumed-rank, but it could also be an explicit-shape
 139 or assumed-size argument.
 140 This means that it may or may not be passed by means of a descriptor.
 141
 142 Note that a `FINAL` subroutine with a scalar argument does not define
 143 a finalizer for array objects unless the subroutine is elemental
 144 (and probably `IMPURE`).
 145 This seems to be a language pitfall and F18 will emit a
 146 warning when an array of a finalizable derived type is declared
 147 with a rank lacking a `FINAL` subroutine when other ranks do have one.
 148
 149 So the necessary information in the derived type table for a `FINAL`
 150 subroutine comprises:
 151 * address(es) of the subroutine
 152 * rank of the argument, or whether it is assumed-rank
 153 * for rank 0, whether the subroutine is elemental
 154 * for rank > 0, whether the argument requires a descriptor
 155
 156 This descriptor flag is needed to handle a difficult case with
 157 `FINAL` subroutines that most other implementations of Fortran
 158 fail to get right: a `FINAL` subroutine
 159 whose argument is a an explicit shape or assumed size array may
 160 have to be called upon the parent component of an array of
 161 an extended derived type.
 162
 163 ```
 164   module m
 165     type :: parent
 166       integer :: n
 167      contains
 168       final :: subr
 169     end type
 170     type, extends(parent) :: extended
 171       integer :: m
 172     end type
 173    contains
 174     subroutine subr(a)
 175       type(parent) :: a(1)
 176     end subroutine
 177   end module
 178   subroutine demo
 179     use m
 180     type(extended) :: arr(1)
 181   end subroutine
 182 ```
 183
 184 If the `FINAL` subroutine doesn't use a descriptor -- and it
 185 will not if there are no `LEN` type parameters -- the runtime
 186 will have to allocate and populate a temporary array of copies
 187 elements of the parent component of the array so that it can
 188 be passed by reference to the `FINAL` subroutine.
 189
 190 ### Defined assignment
 191
 192 A defined assignment subroutine for a derived type can be declared
 193 by means of a generic `INTERFACE ASSIGNMENT(=)` and by means of
 194 a generic type-bound procedure.
 195 Defined assignments with non-type-bound generic interfaces are
 196 resolved to specific subroutines at compilation time.
 197 Most cases of type-bound defined assignment are resolved to their
 198 bindings at compilation time as well (with possible runtime
 199 resolution of overridable bindings).
 200
 201 Intrinsic assignment of derived types with components that have
 202 derived types with type-bound generic assignments is specified
 203 by subclause 10.2.1.3 paragraph 13 as invoking defined assignment
 204 subroutines, however.
 205
 206 This seems to be the only case of defined assignment that may be of
 207 interest to the runtime library.
 208 If this is correct, then the requirements are somewhat constrained;
 209 we know that the rank of the target of the assignment must match
 210 the rank of the source, and that one of the dummy arguments of the
 211 bound subroutine is a passed object dummy argument and satisfies
 212 all of the constraints of one -- in particular, it's scalar and
 213 polymorphic.
 214
 215 So the derived type information for a defined assignment needs to
 216 comprise:
 217 * address(es) of the subroutine
 218 * whether the first, second, or both arguments are descriptors
 219 * whether the subroutine is elemental (necessarily also impure)
 220
 221 ### User defined derived type I/O
 222
 223 Fortran programs can specify subroutines that implement formatted and
 224 unformatted `READ` and `WRITE` operations for derived types.
 225 These defined I/O subroutines may be specified with an explicit `INTERFACE`
 226 or with a type-bound generic.
 227 When specified with an `INTERFACE`, the first argument must not be
 228 polymorphic, but when specified with a type-bound generic, the first
 229 argument is a passed-object dummy argument and required to be so.
 230 In any case, the argument is scalar.
 231
 232 Nearly all invocations of user defined derived type I/O subroutines
 233 are resolved at compilation time to specific procedures or to
 234 overridable bindings.
 235 (The I/O library APIs for acquiring their arguments remain to be
 236 designed, however.)
 237 The case that is of interest to the runtime library is that of
 238 NAMELIST I/O, which is specified to invoke user defined derived
 239 type I/O subroutines if they have been defined.
 240
 241 The derived type information for a user defined derived type I/O
 242 subroutine comprises:
 243 * address(es) of the subroutine
 244 * whether it is for a read or a write
 245 * whether it is formatted or unformatted
 246 * whether the first argument is a descriptor (true if it is a
 247   binding of the derived type, or has a `LEN` type parameter)
 248
 249 ## Exporting derived type descriptions from module relocatables
 250
 251 Subclause 7.5.2 requires that two objects be considered as having the
 252 same derived type if they are declared "with reference to the same
 253 derived type definition".
 254 For derived types that are defined in modules and accessed by means
 255 of use association, we need to be able to describe the type in the
 256 read-only static data section of the module and access the description
 257 as a link-time external.
 258
 259 This is not always possible to achieve in the case of instantiations
 260 of parameterized derived types, however.
 261 Two identical instantiations in distinct compilation units of the same
 262 use associated parameterized derived type seem impractical to implement
 263 using the same address.
 264 (Perhaps some linkers would support unification of global objects
 265 with "mangled" names and identical contents, but this seems unportable.)
 266
 267 Derived type descriptions therefore will contain pointers to
 268 their "uninstantiated" original derived types.
 269 For derived types with no `KIND` type parameters, these pointers
 270 will be null; for uninstantiated derived types, these pointers
 271 will point at themselves.