gcc/ada/freeze.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                               F R E E Z E                                --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2024, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 with Types; use Types;
  27
  28 package Freeze is
  29
  30    --------------------------
  31    -- Handling of Freezing --
  32    --------------------------
  33
  34    --  In the formal Ada semantics, freezing of entities occurs at a well
  35    --  defined point, described in (RM 13.14). The model in GNAT of freezing
  36    --  is that a Freeze_Entity node is generated at the point where an entity
  37    --  is frozen, and the entity contains a pointer (Freeze_Node) to this
  38    --  generated freeze node.
  39
  40    --  The freeze node is processed in the expander to generate associated
  41    --  data and subprograms (e.g. an initialization procedure) which must
  42    --  be delayed until the type is frozen and its representation can be
  43    --  fully determined. Subsequently the freeze node is used by Gigi to
  44    --  determine the point at which it should elaborate the corresponding
  45    --  entity (this elaboration also requires the representation of the
  46    --  entity to be fully determinable). The freeze node is also used to
  47    --  provide additional diagnostic information (pinpointing the freeze
  48    --  point), when order of freezing errors are detected.
  49
  50    --  If we were fully faithful to the Ada model, we would generate freeze
  51    --  nodes for all entities, but that is a bit heavy so we optimize (that
  52    --  is the nice word) or cut corners (which is a bit more honest). For
  53    --  many entities, we do not need to delay the freeze and instead can
  54    --  freeze them at the point of declaration. The conditions for this
  55    --  early freezing being permissible are as follows:
  56
  57    --    There is no associated expander activity that needs to be delayed
  58
  59    --    Gigi can fully elaborate the entity at the point of occurrence (or,
  60    --    equivalently, no real elaboration is required for the entity).
  61
  62    --  In order for these conditions to be met (especially the second), it
  63    --  must be the case that all representation characteristics of the entity
  64    --  can be determined at declaration time.
  65
  66    --  The following indicates how freezing is handled for all entity kinds:
  67
  68    --    Types
  69
  70    --      All declared types have freeze nodes, as well as anonymous base
  71    --      types created for type declarations where the defining identifier
  72    --      is a first subtype of the anonymous type.
  73
  74    --    Subtypes
  75
  76    --      All first subtypes have freeze nodes. Other subtypes need freeze
  77    --      nodes if the corresponding base type has not yet been frozen. If
  78    --      the base type has been frozen, then there is no need for a freeze
  79    --      node, since no rep clauses can appear for the subtype in any case.
  80
  81    --    Implicit types and subtypes
  82
  83    --      As noted above, implicit base types always have freeze nodes. Other
  84    --      implicit types and subtypes typically do not require freeze nodes,
  85    --      because there is no possibility of delaying any information about
  86    --      their representation.
  87
  88    --    Subprograms
  89    --
  90    --      Are frozen at the point of declaration unless one or more of the
  91    --      formal types or return type themselves have delayed freezing and
  92    --      are not yet frozen. This includes the case of a formal access type
  93    --      where the designated type is not frozen. Note that we are talking
  94    --      about subprogram specs here (subprogram body entities have no
  95    --      relevance), and in any case, subprogram bodies freeze everything.
  96
  97    --    Objects with dynamic address clauses
  98    --
  99    --      These have a delayed freeze. Gigi will generate code to evaluate
 100    --      the initialization expression if present and store it in a temp.
 101    --      The actual object is created at the point of the freeze, and if
 102    --      necessary initialized by copying the value of this temporary.
 103
 104    --    Formal Parameters
 105    --
 106    --      Are frozen when the associated subprogram is frozen, so there is
 107    --      never any need for them to have delayed freezing.
 108
 109    --    Other Objects
 110    --
 111    --      Are always frozen at the point of declaration
 112
 113    --    All Other Entities
 114
 115    --      Are always frozen at the point of declaration
 116
 117    --  The flag Has_Delayed_Freeze is used to indicate that delayed freezing
 118    --  is required. Usually the associated freeze node is allocated at the
 119    --  freezing point. One special exception occurs with anonymous base types,
 120    --  where the freeze node is preallocated at the point of declaration, so
 121    --  that the First_Subtype_Link field can be set.
 122
 123    -----------------
 124    -- Subprograms --
 125    -----------------
 126
 127    function Build_Renamed_Body
 128      (Decl  : Node_Id;
 129       New_S : Entity_Id) return Node_Id;
 130    --  Rewrite renaming declaration as a subprogram body, whose single
 131    --  statement is a call to the renamed entity. New_S is the entity that
 132    --  appears in the renaming declaration. If this is a Renaming_As_Body,
 133    --  then Decl is the original subprogram declaration that is completed
 134    --  by the renaming, otherwise it is the renaming declaration itself.
 135    --  The caller inserts the body where required. If this call comes
 136    --  from a freezing action, the resulting body is analyzed at once.
 137
 138    procedure Check_Compile_Time_Size (T : Entity_Id);
 139    --  Check to see whether the size of the type T is known at compile time.
 140    --  There are three possible cases:
 141    --
 142    --    Size is not known at compile time. In this case, the call has no
 143    --    effect. Note that the processing is conservative here, in the sense
 144    --    that this routine may decide that the size is not known even if in
 145    --    fact Gigi decides it is known, but the opposite situation can never
 146    --    occur.
 147    --
 148    --    Size is known at compile time, but the actual value of the size is not
 149    --    known to the front end or is greater than System_Max_Integer_Size. In
 150    --    this case, Size_Known_At_Compile_Time is set, but the RM_Size field is
 151    --    left set to zero (to be set by Gigi).
 152    --
 153    --    Size is known at compile time, and the actual value of the size is
 154    --    known to the front end and not greater than System_Max_Integer_Size.
 155    --    In this case, Size_Known_At_Compile_Time is set, and in addition the
 156    --    RM_Size field is set to the required size, allowing for possible front
 157    --    end packing of an array using this type as a component type.
 158    --
 159    --  Note: the flag Size_Known_At_Compile_Time is used to determine if the
 160    --  secondary stack must be used to return a value of the type, and also
 161    --  to determine whether a component clause is allowed for a component
 162    --  of the given type.
 163    --
 164    --  Note: this is public because of one dubious use in Sem_Res???
 165    --
 166    --  Note: Check_Compile_Time_Size does not test the case of the size being
 167    --  known because a size clause is specifically given. That is because we
 168    --  do not allow a size clause if the size would not otherwise be known at
 169    --  compile time in any case.
 170
 171    procedure Check_Inherited_Conditions
 172     (R               : Entity_Id;
 173      Late_Overriding : Boolean := False);
 174    --  For a tagged derived type R, create wrappers for inherited operations
 175    --  that have class-wide conditions, so it can be properly rewritten if
 176    --  it involves calls to other overriding primitives. Late_Overriding is
 177    --  True when we are processing the body of a primitive with no previous
 178    --  spec defined after R is frozen (see Check_Dispatching_Operation).
 179
 180    procedure Explode_Initialization_Compound_Statement (E : Entity_Id);
 181    --  If Initialization_Statements (E) is an N_Compound_Statement, insert its
 182    --  actions in the enclosing list and reset the attribute.
 183
 184    function Freeze_Entity
 185      (E                 : Entity_Id;
 186       N                 : Node_Id;
 187       Do_Freeze_Profile : Boolean := True) return List_Id;
 188    --  Freeze an entity, and return Freeze nodes, to be inserted at the point
 189    --  of call. N is a node whose source location corresponds to the freeze
 190    --  point. This is used in placing warning messages in the situation where
 191    --  it appears that a type has been frozen too early, e.g. when a primitive
 192    --  operation is declared after the freezing point of its tagged type.
 193    --  Returns No_List if no freeze nodes needed. Parameter Do_Freeze_Profile
 194    --  is used when E is a subprogram, and determines whether the profile of
 195    --  the subprogram should be frozen as well.
 196
 197    procedure Freeze_All (From : Entity_Id; After : in out Node_Id);
 198    --  Before a non-instance body, or at the end of a declarative part,
 199    --  freeze all entities therein that are not yet frozen. Calls itself
 200    --  recursively to catch types in inner packages that were not frozen
 201    --  at the inner level because they were not yet completely defined.
 202    --  This routine also analyzes and freezes default parameter expressions
 203    --  in subprogram specifications (this has to be delayed until all the
 204    --  types are frozen). The resulting freeze nodes are inserted just
 205    --  after node After (which is a list node) and analyzed. On return,
 206    --  'After' is updated to point to the last node inserted (or is returned
 207    --  unchanged if no nodes were inserted). 'From' is the last entity frozen
 208    --  in the scope. It is used to prevent a quadratic traversal over already
 209    --  frozen entities.
 210
 211    procedure Freeze_Before
 212      (N                 : Node_Id;
 213       T                 : Entity_Id;
 214       Do_Freeze_Profile : Boolean := True);
 215    --  Freeze T then Insert the generated Freeze nodes before the node N. Flag
 216    --  Do_Freeze_Profile is used when T is an overloadable entity and indicates
 217    --  whether its profile should be frozen at the same time.
 218
 219    procedure Freeze_Expression (N : Node_Id);
 220    --  Freezes the required entities when the Expression N causes freezing.
 221    --  The node N here is either a subexpression node (a "real" expression)
 222    --  or a subtype mark, or a subtype indication. The latter two cases are
 223    --  not really expressions, but they can appear within expressions and
 224    --  so need to be similarly treated. Freeze_Expression takes care of
 225    --  determining the proper insertion point for generated freeze actions.
 226
 227    procedure Freeze_Expr_Types
 228      (Def_Id : Entity_Id;
 229       Typ    : Entity_Id;
 230       Expr   : Node_Id;
 231       N      : Node_Id);
 232    --  N is the body constructed for an expression function that is a
 233    --  completion, and Def_Id is the function being completed.
 234    --  This procedure freezes before N all the types referenced in Expr,
 235    --  which is either the expression of the expression function, or
 236    --  the expression in a pre/post aspect that applies to Def_Id;
 237
 238    procedure Freeze_Fixed_Point_Type (Typ : Entity_Id);
 239    --  Freeze fixed point type. For fixed-point types, we have to defer
 240    --  setting the size and bounds till the freeze point, since they are
 241    --  potentially affected by the presence of size and small clauses.
 242
 243    procedure Freeze_Itype (T : Entity_Id; N : Node_Id);
 244    --  This routine is called when an Itype is created and must be frozen
 245    --  immediately at the point of creation (for the sake of the expansion
 246    --  activities in Exp_Ch3 (for example, the creation of packed array
 247    --  types). We can't just let Freeze_Expression do this job since it
 248    --  goes out of its way to make sure that the freeze node occurs at a
 249    --  point outside the current construct, e.g. outside the expression or
 250    --  outside the initialization procedure. That's normally right, but
 251    --  not in this case, since if we create an Itype in an expression it
 252    --  may be the case that it is not always elaborated (for example it
 253    --  may result from the right operand of a short circuit). In this case
 254    --  we want the freeze node to be inserted at the same point as the Itype.
 255    --  The node N provides both the location for the freezing and also the
 256    --  insertion point for the resulting freeze nodes.
 257
 258 end Freeze;