gcc/ada/sem_maps.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                             S E M _ M A P S                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                              $Revision$
  10 --                                                                          --
  11 --          Copyright (C) 1996-2001 Free Software Foundation, Inc.          --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- GNAT was originally developed  by the GNAT team at  New York University. --
  25 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
  26 --                                                                          --
  27 ------------------------------------------------------------------------------
  28
  29 --  This package contains the operations on the renaming maps used for
  30 --  generic analysis and instantiation. Renaming maps are created when
  31 --  a generic unit is analyzed, in order to capture all references to
  32 --  global variables within the unit. The renaming map of a generic unit
  33 --  copied prior to each instantiation, and then updated by mapping the
  34 --  formals into the actuals and the local entities into entities local to
  35 --  the instance. When the generic tree is copied to produce the instance,
  36 --  all references are updated by means of the renaming map.
  37
  38 --  Map composition of renaming maps takes place for nested instantiations,
  39 --  for generic child units, and for formal packages.
  40
  41 --  For additional details, see the documentation in sem_ch12.
  42
  43 with Table;
  44 with Types; use Types;
  45
  46 package Sem_Maps is
  47
  48    type Map is new Int;
  49
  50    type Assoc is private;
  51
  52    type Scope_Kind is (S_Global, S_Formal, S_Local);
  53
  54    function New_Map (Num_Assoc : Int) return Map;
  55    --  Build empty map with the given number of associations, and a
  56    --  headers table of the appropriate size.
  57
  58    function Compose (Orig_Map : Map; New_Map : Map) return Map;
  59    --  Update the associations in Orig_Map, so that if Orig_Map (e1) = e2
  60    --  and New_Map (e2) = e3, then the image of e1 under the result is e3.
  61
  62    function Copy (M : Map) return Map;
  63    --  Full copy of contents and headers.
  64
  65    function Lookup (M : Map; E : Entity_Id) return Entity_Id;
  66    --  Retrieve image of E under M, Empty if undefined.
  67
  68    procedure Add_Association
  69      (M    : in out Map;
  70       O_Id : Entity_Id;
  71       N_Id : Entity_Id;
  72       Kind : Scope_Kind := S_Local);
  73    --  Update M in place. On entry M (O_Id) must not be defined.
  74
  75    procedure Update_Association
  76      (M    : in out Map;
  77       O_Id : Entity_Id;
  78       N_Id : Entity_Id;
  79       Kind : Scope_Kind := S_Local);
  80    --  Update the entry in M for O_Id.
  81
  82    function Build_Instance_Map (M : Map) return Map;
  83    --  Copy renaming map of generic, and create new entities for all the
  84    --  local entities within.
  85
  86 private
  87
  88    --  New maps are created when a generic is analyzed, and for each of
  89    --  its instantiations. Maps are also updated for nested generics, for
  90    --  child units, and for formal packages. As a result we need to allocate
  91    --  maps dynamically.
  92
  93    --  When analyzing a generic, we do not know how many references are
  94    --  in it. We build an initial map after generic analysis, using a static
  95    --  structure that relies on the compiler's extensible table mechanism.
  96    --  After constructing this initial map, all subsequent uses and updates
  97    --  of this map do not modify its domain, so that dynamically allocated
  98    --  maps have a fixed size and never need to be reallocated. Furthermore,
  99    --  the headers of the hash table of a dynamically allocated map can be
 100    --  chosen according to the total number of entries in the map, to
 101    --  accommodate efficiently generic units of different sizes (Unchecked_
 102    --  Conversion vs. Generic_Elementary_Functions, for example). So in
 103    --  fact both components of a map have fixed size, and can be allocated
 104    --  using the standard table mechanism. A Maps_Table holds records that
 105    --  contain indices into the global Headers table and the Associations
 106    --  table, and a Map is an index into the Maps_Table.
 107    --
 108    --              Maps_Table          Headers_Table     Associations_Table
 109    --
 110    --                                    |_____|          |___________ |
 111    --               |_____|              |     |          |            |
 112    --        ------>|Map  |------------------------------>|Associations|
 113    --               |Info |------------->|     |=========>| for one    |
 114    --               |_____|              |     |====|     |   unit     |
 115    --               |     |              |     |    |====>|            |
 116    --                                    |_____|          |____________|
 117    --                                    |     |          |            |
 118    type Header_Index is new Int;
 119    type Assoc_Index  is new Int;
 120    No_Assoc : constant Assoc_Index := -1;
 121
 122    type Map_Info is record
 123       Header_Offset : Header_Index;
 124       Header_Num    : Header_Index;
 125       Assoc_Offset  : Assoc_Index;
 126       Assoc_Num     : Assoc_Index;
 127       Assoc_Next    : Assoc_Index;
 128    end record;
 129
 130    type Assoc is record
 131       Old_Id : Entity_Id   := Empty;
 132       New_Id : Entity_Id   := Empty;
 133       Kind   : Scope_Kind  := S_Local;
 134       Next   : Assoc_Index := No_Assoc;
 135    end record;
 136
 137    --  All maps are accessed through the following table. The map attribute
 138    --  of a generic unit or an instance is an index into this table.
 139
 140    package Maps_Table is new Table.Table (
 141       Table_Component_Type => Map_Info,
 142       Table_Index_Type     => Map,
 143       Table_Low_Bound      => 0,
 144       Table_Initial        => 100,
 145       Table_Increment      => 10,
 146       Table_Name           => "Maps_Table");
 147
 148    --  All headers for hash tables are allocated in one global table. Each
 149    --  map stores the offset into this table at which its own headers start.
 150
 151    package Headers_Table is new Table.Table (
 152       Table_Component_Type => Assoc_Index,
 153       Table_Index_Type     => Header_Index,
 154       Table_Low_Bound      => 0,
 155       Table_Initial        => 1000,
 156       Table_Increment      => 10,
 157       Table_Name           => "Headers_Table");
 158
 159    --  All associations are allocated in one global table. Each map stores
 160    --  the offset into this table at which its own associations start.
 161
 162    package Associations_Table is new Table.Table (
 163       Table_Component_Type => Assoc,
 164       Table_Index_Type     => Assoc_Index,
 165       Table_Low_Bound      => 1,
 166       Table_Initial        => 1000,
 167       Table_Increment      => 10,
 168       Table_Name           => "Associations_Table");
 169
 170 end Sem_Maps;