gcc/ada/exp_tss.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              E X P _ T S S                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2006, 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 2,  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 COPYING.  If not, write --
  19 -- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
  20 -- Boston, MA 02110-1301, USA.                                              --
  21 --                                                                          --
  22 -- GNAT was originally developed  by the GNAT team at  New York University. --
  23 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  24 --                                                                          --
  25 ------------------------------------------------------------------------------
  26
  27 --  Type Support Subprogram (TSS) handling
  28
  29 with Types; use Types;
  30
  31 package Exp_Tss is
  32
  33    --  A type support subprogram (TSS) is an internally generated function or
  34    --  procedure that is associated with a particular type. Examples are the
  35    --  implicit initialization procedure, and subprograms for the Input and
  36    --  Output attributes.
  37
  38    --  A given TSS is either generated once at the point of the declaration of
  39    --  the type, or it is generated as needed in clients, but only one copy is
  40    --  required in any one generated object file. The choice between these two
  41    --  possibilities is made on a TSS-by-TSS basis depending on the estimation
  42    --  of how likely the TSS is to be used. Initialization procedures fall in
  43    --  the first category, for example, since it is likely that any declared
  44    --  type will be used in a context requiring initialization, but the stream
  45    --  attributes use the second approach, since it is more likely that they
  46    --  will not be used at all, or will only be used in one client in any case.
  47
  48    -------------------------
  49    -- Current Limitations --
  50    -------------------------
  51
  52    --  In the current version of this package, only the case of generating a
  53    --  TSS at the point of declaration of the type is accomodated. A clear
  54    --  improvement would be to follow through with the full implementation
  55    --  as described above, and also accomodate the requirement of generating
  56    --  only one copy in a given object file.
  57
  58    --  For now, we deal with the local case by generating duplicate versions
  59    --  of the TSS routine, which is clearly rather inefficient in space usage.
  60    --  This is done by using Make_TSS_Name_Local to generate unique names
  61    --  for the different instances of TSS routines in a given scope.
  62
  63    ----------------
  64    -- TSS Naming --
  65    ----------------
  66
  67    --  A TSS is identified by its Chars name. The name has the form typXY or
  68    --  typ_<serial>XY, where typ is the type name, and XY are two characters
  69    --  that identify the particular TSS routine. A unique serial number is
  70    --  included for the case where several local instances of the same TSS
  71    --  must be generated (see discussion under Make_TSS_Name_Local).
  72
  73    --  The following codes are used to denote TSSs:
  74
  75    --  Note: When making additions to this list, update the list in snames.adb
  76
  77    type TSS_Name_Type is new String (1 .. 2);
  78    subtype TNT is TSS_Name_Type;
  79
  80    TSS_Deep_Adjust        : constant TNT := "DA";  -- Deep Adjust
  81    TSS_Deep_Finalize      : constant TNT := "DF";  -- Deep Finalize
  82    TSS_Deep_Initialize    : constant TNT := "DI";  -- Deep Initialize
  83    TSS_Composite_Equality : constant TNT := "EQ";  -- Composite Equality
  84    TSS_From_Any           : constant TNT := "FA";  -- PolyORB/DSA From_Any
  85    TSS_Init_Proc          : constant TNT := "IP";  -- Initialization Procedure
  86    TSS_RAS_Access         : constant TNT := "RA";  -- RAS type access
  87    TSS_RAS_Dereference    : constant TNT := "RD";  -- RAS type deference
  88    TSS_Rep_To_Pos         : constant TNT := "RP";  -- Rep to Pos conversion
  89    TSS_Slice_Assign       : constant TNT := "SA";  -- Slice assignment
  90    TSS_Stream_Input       : constant TNT := "SI";  -- Stream Input attribute
  91    TSS_Stream_Output      : constant TNT := "SO";  -- Stream Output attribute
  92    TSS_Stream_Read        : constant TNT := "SR";  -- Stream Read attribute
  93    TSS_Stream_Write       : constant TNT := "SW";  -- Stream Write attribute
  94    TSS_To_Any             : constant TNT := "TA";  -- PolyORB/DSA To_Any
  95    TSS_TypeCode           : constant TNT := "TC";  -- PolyORB/DSA TypeCode
  96
  97    --  The array below contains all valid TSS names
  98
  99    TSS_Names : constant array (Natural range <>) of TSS_Name_Type :=
 100      (TSS_Deep_Adjust,
 101       TSS_Deep_Finalize,
 102       TSS_Deep_Initialize,
 103       TSS_Composite_Equality,
 104       TSS_From_Any,
 105       TSS_Init_Proc,
 106       TSS_RAS_Access,
 107       TSS_RAS_Dereference,
 108       TSS_Rep_To_Pos,
 109       TSS_Slice_Assign,
 110       TSS_Stream_Input,
 111       TSS_Stream_Output,
 112       TSS_Stream_Read,
 113       TSS_Stream_Write,
 114       TSS_To_Any,
 115       TSS_TypeCode);
 116
 117    TSS_Null : constant TNT := "  ";
 118    --  Dummy entry used to indicated that this is not really a TSS
 119
 120    function Get_TSS_Name (E : Entity_Id) return TSS_Name_Type;
 121    --  Given an entity, if it is a TSS, then return the corresponding TSS
 122    --  name type, otherwise return TSS_Null.
 123
 124    function Make_TSS_Name
 125      (Typ : Entity_Id;
 126       Nam : TSS_Name_Type) return Name_Id;
 127    --  Construct the name as described above for the given TSS routine
 128    --  identified by Nam for the type identified by Typ.
 129
 130    function Make_TSS_Name_Local
 131      (Typ : Entity_Id;
 132       Nam : TSS_Name_Type) return Name_Id;
 133    --  Similar to the above call, but a string of the form _nnn is inserted
 134    --  before the TSS code suffix, where nnn is a unique serial number. This
 135    --  is used when multiple instances of the same TSS routine may be
 136    --  generated in the same scope (see also discussion above of current
 137    --  limitations).
 138
 139    function Make_Init_Proc_Name (Typ : Entity_Id) return Name_Id;
 140    --  Version for init procs, same as Make_TSS_Name (Typ, TSS_Init_Proc)
 141
 142    function Is_TSS (E : Entity_Id; Nam : TSS_Name_Type) return Boolean;
 143    --  Determines if given entity (E) is the name of a TSS identified by Nam
 144
 145    function Is_TSS (N : Name_Id; Nam : TSS_Name_Type) return Boolean;
 146    --  Same test applied directly to a Name_Id value
 147
 148    function Is_Init_Proc (E : Entity_Id) return Boolean;
 149    --  Version for init procs, same as Is_TSS (E, TSS_Init_Proc);
 150
 151    -----------------------------------------
 152    -- TSS Data structures and Subprograms --
 153    -----------------------------------------
 154
 155    --  The TSS's for a given type are stored in an element list associated with
 156    --  the type, and referenced from the TSS_Elist field of the N_Freeze_Entity
 157    --  node associated with the type (all types that need TSS's always need to
 158    --  be explicitly frozen, so the N_Freeze_Entity node always exists).
 159
 160    function TSS (Typ : Entity_Id; Nam : TSS_Name_Type) return Entity_Id;
 161    --  Finds the TSS with the given name associated with the given type
 162    --  If no such TSS exists, then Empty is returned;
 163
 164    function TSS (Typ : Entity_Id; Nam : Name_Id) return Entity_Id;
 165    --  Finds the TSS with the given name associated with the given type. If
 166    --  no such TSS exists, then Empty is returned.
 167
 168    function Same_TSS (E1, E2 : Entity_Id) return Boolean;
 169    --  Returns True if E1 and E2 are the same kind of TSS, even if the names
 170    --  are different (i.e. if the names of E1 and E2 end with two upper case
 171    --  letters that are the same).
 172
 173    procedure Set_TSS (Typ : Entity_Id; TSS : Entity_Id);
 174    --  This procedure is used to install a newly created TSS. The second
 175    --  argument is the entity for such a new TSS. This entity is placed in the
 176    --  TSS list for the type given as the first argument, replacing an old
 177    --  entry of the same name if one was present. The tree for the body of this
 178    --  TSS, which is not analyzed yet, is placed in the actions field of the
 179    --  freeze node for the type. All such bodies are inserted into the main
 180    --  tree and analyzed at the point at which the freeze node itself is
 181    --  expanded.
 182
 183    procedure Copy_TSS (TSS : Entity_Id; Typ : Entity_Id);
 184    --  Given an existing TSS for another type (which is already installed,
 185    --  analyzed and expanded), install it as the corresponding TSS for Typ.
 186    --  Note that this just copies a reference, not the tree. This can also be
 187    --  used to initially install a TSS in the case where the subprogram for the
 188    --  TSS has already been created and its declaration processed.
 189
 190    function Init_Proc (Typ : Entity_Id) return Entity_Id;
 191    pragma Inline (Init_Proc);
 192    --  Obtains the _init TSS entry for the given type. This function call is
 193    --  equivalent to TSS (Typ, Name_uInit). The _init TSS is the procedure
 194    --  used to initialize otherwise uninitialized instances of a type. If
 195    --  there is no _init TSS, then the type requires no initialization. Note
 196    --  that subtypes and implicit types never have an _init TSS since subtype
 197    --  objects are always initialized using the initialization procedure for
 198    --  the corresponding base type (see Base_Init_Proc function). A special
 199    --  case arises for concurrent types. Such types do not themselves have an
 200    --  init proc TSS, but initialization is required. The init proc used is
 201    --  the one fot the corresponding record type (see Base_Init_Proc).
 202
 203    function Base_Init_Proc (Typ : Entity_Id) return Entity_Id;
 204    --  Obtains the _Init TSS entry from the base type of the entity, and also
 205    --  deals with going indirect through the Corresponding_Record_Type field
 206    --  for concurrent objects (which are initialized with the initialization
 207    --  routine for the corresponding record type). Returns Empty if there is
 208    --  no _Init TSS entry for the base type.
 209
 210    procedure Set_Init_Proc (Typ : Entity_Id; Init : Entity_Id);
 211    pragma Inline (Set_Init_Proc);
 212    --  The second argument is the _init TSS to be established for the type
 213    --  given as the first argument. Equivalent to Set_TSS (Typ, Init).
 214
 215    function Has_Non_Null_Base_Init_Proc (Typ : Entity_Id) return Boolean;
 216    --  Returns true if the given type has a defined Base_Init_Proc and
 217    --  this init proc is not a null init proc (null init procs occur as
 218    --  a result of the processing for Initialize_Scalars. This function
 219    --  is used to test for the presence of an init proc in cases where
 220    --  a null init proc is considered equivalent to no init proc.
 221
 222    function Find_Inherited_TSS
 223      (Typ : Entity_Id;
 224       Nam : TSS_Name_Type) return Entity_Id;
 225    --  Returns the TSS of name Nam of Typ, or of its closest ancestor defining
 226    --  such a TSS. Empty is returned is neither Typ nor any of its ancestors
 227    --  have such a TSS.
 228
 229 end Exp_Tss;