gcc/ada/a-tags.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --                             A D A . T A G S                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2007, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- This specification is derived from the Ada Reference Manual for use with --
  12 -- GNAT. The copyright notice above, and the license provisions that follow --
  13 -- apply solely to the  contents of the part following the private keyword. --
  14 --                                                                          --
  15 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  16 -- terms of the  GNU General Public License as published  by the Free Soft- --
  17 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  18 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  19 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  20 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  21 -- for  more details.  You should have  received  a copy of the GNU General --
  22 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  23 -- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
  24 -- Boston, MA 02110-1301, USA.                                              --
  25 --                                                                          --
  26 -- As a special exception,  if other files  instantiate  generics from this --
  27 -- unit, or you link  this unit with other files  to produce an executable, --
  28 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  29 -- covered  by the  GNU  General  Public  License.  This exception does not --
  30 -- however invalidate  any other reasons why  the executable file  might be --
  31 -- covered by the  GNU Public License.                                      --
  32 --                                                                          --
  33 -- GNAT was originally developed  by the GNAT team at  New York University. --
  34 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  35 --                                                                          --
  36 ------------------------------------------------------------------------------
  37
  38 with System;
  39 with System.Storage_Elements;
  40
  41 package Ada.Tags is
  42    pragma Preelaborate_05;
  43    --  In accordance with Ada 2005 AI-362
  44
  45    type Tag is private;
  46    pragma Preelaborable_Initialization (Tag);
  47
  48    No_Tag : constant Tag;
  49
  50    function Expanded_Name (T : Tag) return String;
  51
  52    function Wide_Expanded_Name (T : Tag) return Wide_String;
  53    pragma Ada_05 (Wide_Expanded_Name);
  54
  55    function Wide_Wide_Expanded_Name (T : Tag) return Wide_Wide_String;
  56    pragma Ada_05 (Wide_Wide_Expanded_Name);
  57
  58    function External_Tag (T : Tag) return String;
  59
  60    function Internal_Tag (External : String) return Tag;
  61
  62    function Descendant_Tag
  63      (External : String;
  64       Ancestor : Tag) return Tag;
  65    pragma Ada_05 (Descendant_Tag);
  66
  67    function Is_Descendant_At_Same_Level
  68      (Descendant : Tag;
  69       Ancestor   : Tag) return Boolean;
  70    pragma Ada_05 (Is_Descendant_At_Same_Level);
  71
  72    function Parent_Tag (T : Tag) return Tag;
  73    pragma Ada_05 (Parent_Tag);
  74
  75    type Tag_Array is array (Positive range <>) of Tag;
  76
  77    function Interface_Ancestor_Tags (T : Tag) return Tag_Array;
  78    pragma Ada_05 (Interface_Ancestor_Tags);
  79
  80    Tag_Error : exception;
  81
  82 private
  83    --  Structure of the GNAT Primary Dispatch Table
  84
  85    --           +--------------------+
  86    --           |      Signature     |
  87    --           +--------------------+
  88    --           |     Tagged_Kind    |
  89    --           +--------------------+                            Predef Prims
  90    --           |    Predef_Prims -----------------------------> +------------+
  91    --           +--------------------+                           |  table of  |
  92    --           |    Offset_To_Top   |                           | predefined |
  93    --           +--------------------+                           | primitives |
  94    --           |Typeinfo_Ptr/TSD_Ptr---> Type Specific Data     +------------+
  95    --  Tag ---> +--------------------+   +-------------------+
  96    --           |      table of      |   | inheritance depth |
  97    --           :   primitive ops    :   +-------------------+
  98    --           |      pointers      |   |   access level    |
  99    --           +--------------------+   +-------------------+
 100    --                                    |   expanded name   |
 101    --                                    +-------------------+
 102    --                                    |   external tag    |
 103    --                                    +-------------------+
 104    --                                    |   hash table link |
 105    --                                    +-------------------+
 106    --                                    | remotely callable |
 107    --                                    +-------------------+
 108    --                                    | rec ctrler offset |
 109    --                                    +-------------------+
 110    --                                    |   Ifaces_Table   ---> Interface Data
 111    --                                    +-------------------+   +------------+
 112    --         Select Specific Data  <----        SSD         |   |  Nb_Ifaces |
 113    --         +------------------+       +-------------------+   +------------+
 114    --         |table of primitive|       | table of          |   |  table     |
 115    --         :   operation      :       :    ancestor       :   :    of      :
 116    --         |      kinds       |       |       tags        |   | interfaces |
 117    --         +------------------+       +-------------------+   +------------+
 118    --         |table of          |
 119    --         :   entry          :
 120    --         |      indices     |
 121    --         +------------------+
 122
 123    --  Structure of the GNAT Secondary Dispatch Table
 124
 125    --           +-----------------------+
 126    --           |       table of        |
 127    --           :  predefined primitive :
 128    --           |     ops pointers      |
 129    --           +-----------------------+
 130    --           |       Signature       |
 131    --           +-----------------------+
 132    --           |      Tagged_Kind      |
 133    --           +-----------------------+
 134    --           |     Offset_To_Top     |
 135    --           +-----------------------+
 136    --           |        OSD_Ptr        |---> Object Specific Data
 137    --  Tag ---> +-----------------------+      +---------------+
 138    --           |        table of       |      | num prim ops  |
 139    --           :      primitive op     :      +---------------+
 140    --           |     thunk pointers    |      | table of      |
 141    --           +-----------------------+      +   primitive   |
 142    --                                          |    op offsets |
 143    --                                          +---------------+
 144
 145    --  The runtime information kept for each tagged type is separated into two
 146    --  objects: the Dispatch Table and the Type Specific Data record.
 147
 148    package SSE renames System.Storage_Elements;
 149
 150    subtype Cstring is String (Positive);
 151    type Cstring_Ptr is access all Cstring;
 152    pragma No_Strict_Aliasing (Cstring_Ptr);
 153
 154    --  Declarations for the table of interfaces
 155
 156    type Offset_To_Top_Function_Ptr is
 157      access function (This : System.Address) return SSE.Storage_Offset;
 158    --  Type definition used to call the function that is generated by the
 159    --  expander in case of tagged types with discriminants that have secondary
 160    --  dispatch tables. This function provides the Offset_To_Top value in this
 161    --  specific case.
 162
 163    type Interface_Data_Element is record
 164       Iface_Tag            : Tag;
 165       Static_Offset_To_Top : Boolean;
 166       Offset_To_Top_Value  : SSE.Storage_Offset;
 167       Offset_To_Top_Func   : Offset_To_Top_Function_Ptr;
 168    end record;
 169    --  If some ancestor of the tagged type has discriminants the field
 170    --  Static_Offset_To_Top is False and the field Offset_To_Top_Func
 171    --  is used to store the access to the function generated by the
 172    --  expander which provides this value; otherwise Static_Offset_To_Top
 173    --  is True and such value is stored in the Offset_To_Top_Value field.
 174
 175    type Interfaces_Array is array (Natural range <>) of Interface_Data_Element;
 176
 177    type Interface_Data (Nb_Ifaces : Positive) is record
 178       Ifaces_Table : Interfaces_Array (1 .. Nb_Ifaces);
 179    end record;
 180
 181    type Interface_Data_Ptr is access all Interface_Data;
 182    --  Table of abstract interfaces used to give support to backward interface
 183    --  conversions and also to IW_Membership.
 184
 185    --  Primitive operation kinds. These values differentiate the kinds of
 186    --  callable entities stored in the dispatch table. Certain kinds may
 187    --  not be used, but are added for completeness.
 188
 189    type Prim_Op_Kind is
 190      (POK_Function,
 191       POK_Procedure,
 192       POK_Protected_Entry,
 193       POK_Protected_Function,
 194       POK_Protected_Procedure,
 195       POK_Task_Entry,
 196       POK_Task_Function,
 197       POK_Task_Procedure);
 198
 199    --  Select specific data types
 200
 201    type Select_Specific_Data_Element is record
 202       Index : Positive;
 203       Kind  : Prim_Op_Kind;
 204    end record;
 205
 206    type Select_Specific_Data_Array is
 207      array (Positive range <>) of Select_Specific_Data_Element;
 208
 209    type Select_Specific_Data (Nb_Prim : Positive) is record
 210       SSD_Table : Select_Specific_Data_Array (1 .. Nb_Prim);
 211       --  NOTE: Nb_Prim is the number of non-predefined primitive operations
 212    end record;
 213
 214    type Select_Specific_Data_Ptr is access all Select_Specific_Data;
 215    --  A table used to store the primitive operation kind and entry index of
 216    --  primitive subprograms of a type that implements a limited interface.
 217    --  The Select Specific Data table resides in the Type Specific Data of a
 218    --  type. This construct is used in the handling of dispatching triggers
 219    --  in select statements.
 220
 221    type Tag_Table is array (Natural range <>) of Tag;
 222
 223    type Type_Specific_Data (Idepth : Natural) is record
 224    --  The discriminant Idepth is the Inheritance Depth Level: Used to
 225    --  implement the membership test associated with single inheritance of
 226    --  tagged types in constant-time. It also indicates the size of the
 227    --  Tags_Table component.
 228
 229       Access_Level : Natural;
 230       --  Accessibility level required to give support to Ada 2005 nested type
 231       --  extensions. This feature allows safe nested type extensions by
 232       --  shifting the accessibility checks to certain operations, rather than
 233       --  being enforced at the type declaration. In particular, by performing
 234       --  run-time accessibility checks on class-wide allocators, class-wide
 235       --  function return, and class-wide stream I/O, the danger of objects
 236       --  outliving their type declaration can be eliminated (Ada 2005: AI-344)
 237
 238       Expanded_Name : Cstring_Ptr;
 239       External_Tag  : Cstring_Ptr;
 240       HT_Link       : Tag;
 241       --  Components used to support to the Ada.Tags subprograms in RM 3.9
 242
 243       --  Note: Expanded_Name is referenced by GDB to determine the actual name
 244       --  of the tagged type. Its requirements are: 1) it must have this exact
 245       --  name, and 2) its contents must point to a C-style Nul terminated
 246       --  string containing its expanded name. GDB has no requirement on a
 247       --  given position inside the record.
 248
 249       Transportable : Boolean;
 250       --  Used to check RM E.4(18), set for types that satisfy the requirements
 251       --  for being used in remote calls as actuals for classwide formals or as
 252       --  return values for classwide functions.
 253
 254       RC_Offset : SSE.Storage_Offset;
 255       --  Controller Offset: Used to give support to tagged controlled objects
 256       --  (see Get_Deep_Controller at s-finimp)
 257
 258       Interfaces_Table : Interface_Data_Ptr;
 259       --  Pointer to the table of interface tags. It is used to implement the
 260       --  membership test associated with interfaces and also for backward
 261       --  abstract interface type conversions (Ada 2005:AI-251)
 262
 263       SSD : Select_Specific_Data_Ptr;
 264       --  Pointer to a table of records used in dispatching selects. This
 265       --  field has a meaningful value for all tagged types that implement
 266       --  a limited, protected, synchronized or task interfaces and have
 267       --  non-predefined primitive operations.
 268
 269       Tags_Table : Tag_Table (0 .. Idepth);
 270       --  Table of ancestor tags. Its size actually depends on the inheritance
 271       --  depth level of the tagged type.
 272    end record;
 273
 274    type Type_Specific_Data_Ptr is access all Type_Specific_Data;
 275    pragma No_Strict_Aliasing (Type_Specific_Data_Ptr);
 276
 277    --  Declarations for the dispatch table record
 278
 279    type Signature_Kind is
 280       (Unknown,
 281        Primary_DT,
 282        Secondary_DT);
 283
 284    --  Tagged type kinds with respect to concurrency and limitedness
 285
 286    type Tagged_Kind is
 287      (TK_Abstract_Limited_Tagged,
 288       TK_Abstract_Tagged,
 289       TK_Limited_Tagged,
 290       TK_Protected,
 291       TK_Tagged,
 292       TK_Task);
 293
 294    type Address_Array is array (Positive range <>) of System.Address;
 295
 296    type Dispatch_Table_Wrapper (Num_Prims : Natural) is record
 297       Signature     : Signature_Kind;
 298       Tag_Kind      : Tagged_Kind;
 299       Predef_Prims  : System.Address;
 300       --  Pointer to the dispatch table of predefined Ada primitives
 301
 302       --  According to the C++ ABI the components Offset_To_Top and TSD are
 303       --  stored just "before" the dispatch table, and they are referenced with
 304       --  negative offsets referring to the base of the dispatch table. The
 305       --   _Tag (or the VTable_Ptr in C++ terminology) must point to the base
 306       --  of the virtual table, just after these components, to point to the
 307       --  Prims_Ptr table.
 308
 309       Offset_To_Top : SSE.Storage_Offset;
 310       TSD           : System.Address;
 311
 312       Prims_Ptr : aliased Address_Array (1 .. Num_Prims);
 313       --  The size of the Prims_Ptr array actually depends on the tagged type
 314       --  to which it applies. For each tagged type, the expander computes the
 315       --  actual array size, allocates the Dispatch_Table record accordingly.
 316    end record;
 317
 318    subtype Dispatch_Table is Address_Array (1 .. 1);
 319    --  Used by GDB to identify the _tags and traverse the run-time structure
 320    --  associated with tagged types. For compatibility with older versions of
 321    --  gdb, its name must not be changed.
 322
 323    type Tag is access all Dispatch_Table;
 324    pragma No_Strict_Aliasing (Tag);
 325
 326    type Interface_Tag is access all Dispatch_Table;
 327
 328    No_Tag : constant Tag := null;
 329
 330    --  The expander ensures that Tag objects reference the Prims_Ptr component
 331    --  of the wrapper.
 332
 333    type Tag_Ptr is access all Tag;
 334    pragma No_Strict_Aliasing (Tag_Ptr);
 335
 336    type Dispatch_Table_Ptr is access all Dispatch_Table_Wrapper;
 337    pragma No_Strict_Aliasing (Dispatch_Table_Ptr);
 338
 339    --  The following type declaration is used by the compiler when the program
 340    --  is compiled with restriction No_Dispatching_Calls. It is also used with
 341    --  interface types to generate the tag and run-time information associated
 342    --  with them.
 343
 344    type No_Dispatch_Table_Wrapper is record
 345       NDT_TSD       : System.Address;
 346       NDT_Prims_Ptr : Natural;
 347    end record;
 348
 349    DT_Predef_Prims_Size : constant SSE.Storage_Count :=
 350                             SSE.Storage_Count
 351                               (1 * (Standard'Address_Size /
 352                                       System.Storage_Unit));
 353    --  Size of the Predef_Prims field of the Dispatch_Table
 354
 355    DT_Offset_To_Top_Size : constant SSE.Storage_Count :=
 356                              SSE.Storage_Count
 357                                (1 * (Standard'Address_Size /
 358                                        System.Storage_Unit));
 359    --  Size of the Offset_To_Top field of the Dispatch Table
 360
 361    DT_Typeinfo_Ptr_Size : constant SSE.Storage_Count :=
 362                             SSE.Storage_Count
 363                               (1 * (Standard'Address_Size /
 364                                       System.Storage_Unit));
 365    --  Size of the Typeinfo_Ptr field of the Dispatch Table
 366
 367    use type System.Storage_Elements.Storage_Offset;
 368
 369    DT_Predef_Prims_Offset : constant SSE.Storage_Count :=
 370                               DT_Typeinfo_Ptr_Size
 371                                 + DT_Offset_To_Top_Size
 372                                 + DT_Predef_Prims_Size;
 373    --  Offset from Prims_Ptr to Predef_Prims component
 374
 375    --  Object Specific Data record of secondary dispatch tables
 376
 377    type Object_Specific_Data_Array is array (Positive range <>) of Positive;
 378
 379    type Object_Specific_Data (OSD_Num_Prims : Positive) is record
 380       OSD_Table : Object_Specific_Data_Array (1 .. OSD_Num_Prims);
 381       --  Table used in secondary DT to reference their counterpart in the
 382       --  select specific data (in the TSD of the primary DT). This construct
 383       --  is used in the handling of dispatching triggers in select statements.
 384       --  Nb_Prim is the number of non-predefined primitive operations.
 385    end record;
 386
 387    type Object_Specific_Data_Ptr is access all Object_Specific_Data;
 388    pragma No_Strict_Aliasing (Object_Specific_Data_Ptr);
 389
 390    --  The following subprogram specifications are placed here instead of
 391    --  the package body to see them from the frontend through rtsfind.
 392
 393    function Base_Address (This : System.Address) return System.Address;
 394    --  Ada 2005 (AI-251): Displace "This" to point to the base address of
 395    --  the object (that is, the address of the primary tag of the object).
 396
 397    function Displace (This : System.Address; T : Tag) return System.Address;
 398    --  Ada 2005 (AI-251): Displace "This" to point to the secondary dispatch
 399    --  table of T.
 400
 401    function DT (T : Tag) return Dispatch_Table_Ptr;
 402    --  Return the pointer to the TSD record associated with T
 403
 404    function Get_Entry_Index (T : Tag; Position : Positive) return Positive;
 405    --  Ada 2005 (AI-251): Return a primitive operation's entry index (if entry)
 406    --  given a dispatch table T and a position of a primitive operation in T.
 407
 408    function Get_Offset_Index
 409      (T        : Tag;
 410       Position : Positive) return Positive;
 411    --  Ada 2005 (AI-251): Given a pointer to a secondary dispatch table (T) and
 412    --  a position of an operation in the DT, retrieve the corresponding
 413    --  operation's position in the primary dispatch table from the Offset
 414    --  Specific Data table of T.
 415
 416    function Get_Prim_Op_Kind
 417      (T        : Tag;
 418       Position : Positive) return Prim_Op_Kind;
 419    --  Ada 2005 (AI-251): Return a primitive operation's kind given a dispatch
 420    --  table T and a position of a primitive operation in T.
 421
 422    function Get_RC_Offset (T : Tag) return SSE.Storage_Offset;
 423    --  Return the Offset of the implicit record controller when the object
 424    --  has controlled components, returns zero if no controlled components.
 425
 426    pragma Export (Ada, Get_RC_Offset, "ada__tags__get_rc_offset");
 427    --  This procedure is used in s-finimp to compute the deep routines
 428    --  it is exported manually in order to avoid changing completely the
 429    --  organization of the run time.
 430
 431    function Get_Tagged_Kind (T : Tag) return Tagged_Kind;
 432    --  Ada 2005 (AI-345): Given a pointer to either a primary or a secondary
 433    --  dispatch table, return the tagged kind of a type in the context of
 434    --  concurrency and limitedness.
 435
 436    function IW_Membership (This : System.Address; T : Tag) return Boolean;
 437    --  Ada 2005 (AI-251): General routine that checks if a given object
 438    --  implements a tagged type. Its common usage is to check if Obj is in
 439    --  Iface'Class, but it is also used to check if a class-wide interface
 440    --  implements a given type (Iface_CW_Typ in T'Class). For example:
 441    --
 442    --      type I is interface;
 443    --      type T is tagged ...
 444    --
 445    --      function Test (O : I'Class) is
 446    --      begin
 447    --         return O in T'Class.
 448    --      end Test;
 449
 450    function Offset_To_Top
 451      (This : System.Address) return SSE.Storage_Offset;
 452    --  Ada 2005 (AI-251): Returns the current value of the offset_to_top
 453    --  component available in the prologue of the dispatch table. If the parent
 454    --  of the tagged type has discriminants this value is stored in a record
 455    --  component just immediately after the tag component.
 456
 457    function Parent_Size
 458      (Obj : System.Address;
 459       T   : Tag) return SSE.Storage_Count;
 460    --  Computes the size the ancestor part of a tagged extension object whose
 461    --  address is 'obj' by calling indirectly the ancestor _size function. The
 462    --  ancestor is the parent of the type represented by tag T. This function
 463    --  assumes that _size is always in slot one of the dispatch table.
 464
 465    pragma Export (Ada, Parent_Size, "ada__tags__parent_size");
 466    --  This procedure is used in s-finimp and is thus exported manually
 467
 468    procedure Register_Tag (T : Tag);
 469    --  Insert the Tag and its associated external_tag in a table for the
 470    --  sake of Internal_Tag
 471
 472    procedure Set_Entry_Index (T : Tag; Position : Positive; Value : Positive);
 473    --  Ada 2005 (AI-345): Set the entry index of a primitive operation in T's
 474    --  TSD table indexed by Position.
 475
 476    procedure Set_Offset_To_Top
 477      (This         : System.Address;
 478       Interface_T  : Tag;
 479       Is_Static    : Boolean;
 480       Offset_Value : SSE.Storage_Offset;
 481       Offset_Func  : Offset_To_Top_Function_Ptr);
 482    --  Ada 2005 (AI-251): Initialize the Offset_To_Top field in the prologue of
 483    --  the dispatch table. In primary dispatch tables the value of "This" is
 484    --  not required (and the compiler passes always the Null_Address value) and
 485    --  the Offset_Value is always cero; in secondary dispatch tables "This"
 486    --  points to the object, Interface_T is the interface for which the
 487    --  secondary dispatch table is being initialized, and Offset_Value is the
 488    --  distance from "This" to the object component containing the tag of the
 489    --  secondary dispatch table.
 490
 491    procedure Set_Prim_Op_Kind
 492      (T        : Tag;
 493       Position : Positive;
 494       Value    : Prim_Op_Kind);
 495    --  Ada 2005 (AI-251): Set the kind of a primitive operation in T's TSD
 496    --  table indexed by Position.
 497
 498    Max_Predef_Prims : constant Positive := 15;
 499    --  Number of reserved slots for predefined ada primitives: Size, Alignment,
 500    --  Read, Write, Input, Output, "=", assignment, deep adjust, deep finalize,
 501    --  async select, conditional select, prim_op kind, task_id, and timed
 502    --  select. The compiler checks that this value is correct.
 503
 504    subtype Predef_Prims_Table  is Address_Array (1 .. Max_Predef_Prims);
 505    type Predef_Prims_Table_Ptr is access Predef_Prims_Table;
 506    pragma No_Strict_Aliasing (Predef_Prims_Table_Ptr);
 507
 508    type Addr_Ptr is access System.Address;
 509    pragma No_Strict_Aliasing (Addr_Ptr);
 510 end Ada.Tags;