1.. _Implementation_Advice: 2 3********************* 4Implementation Advice 5********************* 6 7The main text of the Ada Reference Manual describes the required 8behavior of all Ada compilers, and the GNAT compiler conforms to 9these requirements. 10 11In addition, there are sections throughout the Ada Reference Manual headed 12by the phrase 'Implementation advice'. These sections are not normative, 13i.e., they do not specify requirements that all compilers must 14follow. Rather they provide advice on generally desirable behavior. 15They are not requirements, because they describe behavior that cannot 16be provided on all systems, or may be undesirable on some systems. 17 18As far as practical, GNAT follows the implementation advice in 19the Ada Reference Manual. Each such RM section corresponds to a section 20in this chapter whose title specifies the 21RM section number and paragraph number and the subject of 22the advice. The contents of each section consists of the RM text within 23quotation marks, 24followed by the GNAT interpretation of the advice. Most often, this simply says 25'followed', which means that GNAT follows the advice. However, in a 26number of cases, GNAT deliberately deviates from this advice, in which 27case the text describes what GNAT does and why. 28 29.. index:: Error detection 30 31RM 1.1.3(20): Error Detection 32============================= 33 34 "If an implementation detects the use of an unsupported Specialized Needs 35 Annex feature at run time, it should raise ``Program_Error`` if 36 feasible." 37 38Not relevant. All specialized needs annex features are either supported, 39or diagnosed at compile time. 40 41.. index:: Child Units 42 43RM 1.1.3(31): Child Units 44========================= 45 46 47 "If an implementation wishes to provide implementation-defined 48 extensions to the functionality of a language-defined library unit, it 49 should normally do so by adding children to the library unit." 50 51Followed. 52 53.. index:: Bounded errors 54 55RM 1.1.5(12): Bounded Errors 56============================ 57 58 "If an implementation detects a bounded error or erroneous 59 execution, it should raise ``Program_Error``." 60 61Followed in all cases in which the implementation detects a bounded 62error or erroneous execution. Not all such situations are detected at 63runtime. 64 65.. index:: Pragmas 66 67.. _RM_2_8_16_Pragmas: 68 69RM 2.8(16): Pragmas 70=================== 71 72 "Normally, implementation-defined pragmas should have no semantic effect 73 for error-free programs; that is, if the implementation-defined pragmas 74 are removed from a working program, the program should still be legal, 75 and should still have the same semantics." 76 77The following implementation defined pragmas are exceptions to this 78rule: 79 80+--------------------+-------------------+ 81| Pragma | Explanation | 82+====================+===================+ 83| *Abort_Defer* | Affects semantics | 84+--------------------+-------------------+ 85|*Ada_83* | Affects legality | 86+--------------------+-------------------+ 87|*Assert* | Affects semantics | 88+--------------------+-------------------+ 89|*CPP_Class* | Affects semantics | 90+--------------------+-------------------+ 91|*CPP_Constructor* | Affects semantics | 92+--------------------+-------------------+ 93|*Debug* | Affects semantics | 94+--------------------+-------------------+ 95|*Interface_Name* | Affects semantics | 96+--------------------+-------------------+ 97|*Machine_Attribute* | Affects semantics | 98+--------------------+-------------------+ 99|*Unimplemented_Unit*| Affects legality | 100+--------------------+-------------------+ 101|*Unchecked_Union* | Affects semantics | 102+--------------------+-------------------+ 103 104In each of the above cases, it is essential to the purpose of the pragma 105that this advice not be followed. For details see 106:ref:`Implementation_Defined_Pragmas`. 107 108RM 2.8(17-19): Pragmas 109====================== 110 111 "Normally, an implementation should not define pragmas that can 112 make an illegal program legal, except as follows: 113 114 * A pragma used to complete a declaration, such as a pragma ``Import``; 115 116 * A pragma used to configure the environment by adding, removing, or 117 replacing ``library_items``." 118 119See :ref:`RM_2_8_16_Pragmas`. 120 121.. index:: Character Sets 122 123.. index:: Alternative Character Sets 124 125RM 3.5.2(5): Alternative Character Sets 126======================================= 127 128 "If an implementation supports a mode with alternative interpretations 129 for ``Character`` and ``Wide_Character``, the set of graphic 130 characters of ``Character`` should nevertheless remain a proper 131 subset of the set of graphic characters of ``Wide_Character``. Any 132 character set 'localizations' should be reflected in the results of 133 the subprograms defined in the language-defined package 134 ``Characters.Handling`` (see A.3) available in such a mode. In a mode with 135 an alternative interpretation of ``Character``, the implementation should 136 also support a corresponding change in what is a legal 137 ``identifier_letter``." 138 139Not all wide character modes follow this advice, in particular the JIS 140and IEC modes reflect standard usage in Japan, and in these encoding, 141the upper half of the Latin-1 set is not part of the wide-character 142subset, since the most significant bit is used for wide character 143encoding. However, this only applies to the external forms. Internally 144there is no such restriction. 145 146.. index:: Integer types 147 148RM 3.5.4(28): Integer Types 149=========================== 150 151 "An implementation should support ``Long_Integer`` in addition to 152 ``Integer`` if the target machine supports 32-bit (or longer) 153 arithmetic. No other named integer subtypes are recommended for package 154 ``Standard``. Instead, appropriate named integer subtypes should be 155 provided in the library package ``Interfaces`` (see B.2)." 156 157``Long_Integer`` is supported. Other standard integer types are supported 158so this advice is not fully followed. These types 159are supported for convenient interface to C, and so that all hardware 160types of the machine are easily available. 161 162RM 3.5.4(29): Integer Types 163=========================== 164 165 "An implementation for a two's complement machine should support 166 modular types with a binary modulus up to ``System.Max_Int*2+2``. An 167 implementation should support a non-binary modules up to ``Integer'Last``." 168 169Followed. 170 171.. index:: Enumeration values 172 173RM 3.5.5(8): Enumeration Values 174=============================== 175 176 "For the evaluation of a call on ``S'Pos`` for an enumeration 177 subtype, if the value of the operand does not correspond to the internal 178 code for any enumeration literal of its type (perhaps due to an 179 un-initialized variable), then the implementation should raise 180 ``Program_Error``. This is particularly important for enumeration 181 types with noncontiguous internal codes specified by an 182 enumeration_representation_clause." 183 184Followed. 185 186.. index:: Float types 187 188RM 3.5.7(17): Float Types 189========================= 190 191 "An implementation should support ``Long_Float`` in addition to 192 ``Float`` if the target machine supports 11 or more digits of 193 precision. No other named floating point subtypes are recommended for 194 package ``Standard``. Instead, appropriate named floating point subtypes 195 should be provided in the library package ``Interfaces`` (see B.2)." 196 197``Short_Float`` and ``Long_Long_Float`` are also provided. The 198former provides improved compatibility with other implementations 199supporting this type. The latter corresponds to the highest precision 200floating-point type supported by the hardware. On most machines, this 201will be the same as ``Long_Float``, but on some machines, it will 202correspond to the IEEE extended form. The notable case is all ia32 203(x86) implementations, where ``Long_Long_Float`` corresponds to 204the 80-bit extended precision format supported in hardware on this 205processor. Note that the 128-bit format on SPARC is not supported, 206since this is a software rather than a hardware format. 207 208.. index:: Multidimensional arrays 209 210.. index:: Arrays, multidimensional 211 212RM 3.6.2(11): Multidimensional Arrays 213===================================== 214 215 "An implementation should normally represent multidimensional arrays in 216 row-major order, consistent with the notation used for multidimensional 217 array aggregates (see 4.3.3). However, if a pragma ``Convention`` 218 (``Fortran``, ...) applies to a multidimensional array type, then 219 column-major order should be used instead (see B.5, *Interfacing with Fortran*)." 220 221Followed. 222 223.. index:: Duration'Small 224 225RM 9.6(30-31): Duration'Small 226============================= 227 228 "Whenever possible in an implementation, the value of ``Duration'Small`` 229 should be no greater than 100 microseconds." 230 231Followed. (``Duration'Small`` = 10**(-9)). 232 233 "The time base for ``delay_relative_statements`` should be monotonic; 234 it need not be the same time base as used for ``Calendar.Clock``." 235 236Followed. 237 238RM 10.2.1(12): Consistent Representation 239======================================== 240 241 "In an implementation, a type declared in a pre-elaborated package should 242 have the same representation in every elaboration of a given version of 243 the package, whether the elaborations occur in distinct executions of 244 the same program, or in executions of distinct programs or partitions 245 that include the given version." 246 247Followed, except in the case of tagged types. Tagged types involve 248implicit pointers to a local copy of a dispatch table, and these pointers 249have representations which thus depend on a particular elaboration of the 250package. It is not easy to see how it would be possible to follow this 251advice without severely impacting efficiency of execution. 252 253.. index:: Exception information 254 255RM 11.4.1(19): Exception Information 256==================================== 257 258 "``Exception_Message`` by default and ``Exception_Information`` 259 should produce information useful for 260 debugging. ``Exception_Message`` should be short, about one 261 line. ``Exception_Information`` can be long. ``Exception_Message`` 262 should not include the 263 ``Exception_Name``. ``Exception_Information`` should include both 264 the ``Exception_Name`` and the ``Exception_Message``." 265 266Followed. For each exception that doesn't have a specified 267``Exception_Message``, the compiler generates one containing the location 268of the raise statement. This location has the form 'file_name:line', where 269file_name is the short file name (without path information) and line is the line 270number in the file. Note that in the case of the Zero Cost Exception 271mechanism, these messages become redundant with the Exception_Information that 272contains a full backtrace of the calling sequence, so they are disabled. 273To disable explicitly the generation of the source location message, use the 274Pragma ``Discard_Names``. 275 276.. index:: Suppression of checks 277 278.. index:: Checks, suppression of 279 280RM 11.5(28): Suppression of Checks 281================================== 282 283 "The implementation should minimize the code executed for checks that 284 have been suppressed." 285 286Followed. 287 288.. index:: Representation clauses 289 290RM 13.1 (21-24): Representation Clauses 291======================================= 292 293 "The recommended level of support for all representation items is 294 qualified as follows: 295 296 An implementation need not support representation items containing 297 nonstatic expressions, except that an implementation should support a 298 representation item for a given entity if each nonstatic expression in 299 the representation item is a name that statically denotes a constant 300 declared before the entity." 301 302Followed. In fact, GNAT goes beyond the recommended level of support 303by allowing nonstatic expressions in some representation clauses even 304without the need to declare constants initialized with the values of 305such expressions. 306For example: 307 308.. code-block:: ada 309 310 X : Integer; 311 Y : Float; 312 for Y'Address use X'Address;>> 313 314 315 "An implementation need not support a specification for the ``Size`` 316 for a given composite subtype, nor the size or storage place for an 317 object (including a component) of a given composite subtype, unless the 318 constraints on the subtype and its composite subcomponents (if any) are 319 all static constraints." 320 321Followed. Size Clauses are not permitted on nonstatic components, as 322described above. 323 324 325 "An aliased component, or a component whose type is by-reference, should 326 always be allocated at an addressable location." 327 328Followed. 329 330.. index:: Packed types 331 332RM 13.2(6-8): Packed Types 333========================== 334 335 "If a type is packed, then the implementation should try to minimize 336 storage allocated to objects of the type, possibly at the expense of 337 speed of accessing components, subject to reasonable complexity in 338 addressing calculations. 339 340 The recommended level of support pragma ``Pack`` is: 341 342 For a packed record type, the components should be packed as tightly as 343 possible subject to the Sizes of the component subtypes, and subject to 344 any *record_representation_clause* that applies to the type; the 345 implementation may, but need not, reorder components or cross aligned 346 word boundaries to improve the packing. A component whose ``Size`` is 347 greater than the word size may be allocated an integral number of words." 348 349Followed. Tight packing of arrays is supported for all component sizes 350up to 64-bits. If the array component size is 1 (that is to say, if 351the component is a boolean type or an enumeration type with two values) 352then values of the type are implicitly initialized to zero. This 353happens both for objects of the packed type, and for objects that have a 354subcomponent of the packed type. 355 356 357 "An implementation should support Address clauses for imported 358 subprograms." 359 360Followed. 361 362.. index:: Address clauses 363 364RM 13.3(14-19): Address Clauses 365=============================== 366 367 "For an array ``X``, ``X'Address`` should point at the first 368 component of the array, and not at the array bounds." 369 370Followed. 371 372 "The recommended level of support for the ``Address`` attribute is: 373 374 ``X'Address`` should produce a useful result if ``X`` is an 375 object that is aliased or of a by-reference type, or is an entity whose 376 ``Address`` has been specified." 377 378Followed. A valid address will be produced even if none of those 379conditions have been met. If necessary, the object is forced into 380memory to ensure the address is valid. 381 382 "An implementation should support ``Address`` clauses for imported 383 subprograms." 384 385Followed. 386 387 "Objects (including subcomponents) that are aliased or of a by-reference 388 type should be allocated on storage element boundaries." 389 390Followed. 391 392 "If the ``Address`` of an object is specified, or it is imported or exported, 393 then the implementation should not perform optimizations based on 394 assumptions of no aliases." 395 396Followed. 397 398.. index:: Alignment clauses 399 400RM 13.3(29-35): Alignment Clauses 401================================= 402 403 "The recommended level of support for the ``Alignment`` attribute for 404 subtypes is: 405 406 An implementation should support specified Alignments that are factors 407 and multiples of the number of storage elements per word, subject to the 408 following:" 409 410Followed. 411 412 "An implementation need not support specified Alignments for 413 combinations of Sizes and Alignments that cannot be easily 414 loaded and stored by available machine instructions." 415 416Followed. 417 418 "An implementation need not support specified Alignments that are 419 greater than the maximum ``Alignment`` the implementation ever returns by 420 default." 421 422Followed. 423 424 "The recommended level of support for the ``Alignment`` attribute for 425 objects is: 426 427 Same as above, for subtypes, but in addition:" 428 429Followed. 430 431 "For stand-alone library-level objects of statically constrained 432 subtypes, the implementation should support all alignments 433 supported by the target linker. For example, page alignment is likely to 434 be supported for such objects, but not for subtypes." 435 436Followed. 437 438.. index:: Size clauses 439 440RM 13.3(42-43): Size Clauses 441============================ 442 443 "The recommended level of support for the ``Size`` attribute of 444 objects is: 445 446 A ``Size`` clause should be supported for an object if the specified 447 ``Size`` is at least as large as its subtype's ``Size``, and 448 corresponds to a size in storage elements that is a multiple of the 449 object's ``Alignment`` (if the ``Alignment`` is nonzero)." 450 451Followed. 452 453RM 13.3(50-56): Size Clauses 454============================ 455 456 "If the ``Size`` of a subtype is specified, and allows for efficient 457 independent addressability (see 9.10) on the target architecture, then 458 the ``Size`` of the following objects of the subtype should equal the 459 ``Size`` of the subtype: 460 461 Aliased objects (including components)." 462 463Followed. 464 465 "`Size` clause on a composite subtype should not affect the 466 internal layout of components." 467 468Followed. But note that this can be overridden by use of the implementation 469pragma Implicit_Packing in the case of packed arrays. 470 471 "The recommended level of support for the ``Size`` attribute of subtypes is: 472 473 The ``Size`` (if not specified) of a static discrete or fixed point 474 subtype should be the number of bits needed to represent each value 475 belonging to the subtype using an unbiased representation, leaving space 476 for a sign bit only if the subtype contains negative values. If such a 477 subtype is a first subtype, then an implementation should support a 478 specified ``Size`` for it that reflects this representation." 479 480Followed. 481 482 "For a subtype implemented with levels of indirection, the ``Size`` 483 should include the size of the pointers, but not the size of what they 484 point at." 485 486Followed. 487 488.. index:: Component_Size clauses 489 490RM 13.3(71-73): Component Size Clauses 491====================================== 492 493 "The recommended level of support for the ``Component_Size`` 494 attribute is: 495 496 An implementation need not support specified ``Component_Sizes`` that are 497 less than the ``Size`` of the component subtype." 498 499Followed. 500 501 "An implementation should support specified Component_Sizes that 502 are factors and multiples of the word size. For such 503 Component_Sizes, the array should contain no gaps between 504 components. For other Component_Sizes (if supported), the array 505 should contain no gaps between components when packing is also 506 specified; the implementation should forbid this combination in cases 507 where it cannot support a no-gaps representation." 508 509Followed. 510 511.. index:: Enumeration representation clauses 512 513.. index:: Representation clauses, enumeration 514 515RM 13.4(9-10): Enumeration Representation Clauses 516================================================= 517 518 "The recommended level of support for enumeration representation clauses 519 is: 520 521 An implementation need not support enumeration representation clauses 522 for boolean types, but should at minimum support the internal codes in 523 the range ``System.Min_Int .. System.Max_Int``." 524 525Followed. 526 527.. index:: Record representation clauses 528 529.. index:: Representation clauses, records 530 531RM 13.5.1(17-22): Record Representation Clauses 532=============================================== 533 534 "The recommended level of support for 535 *record_representation_clause*\ s is: 536 537 An implementation should support storage places that can be extracted 538 with a load, mask, shift sequence of machine code, and set with a load, 539 shift, mask, store sequence, given the available machine instructions 540 and run-time model." 541 542Followed. 543 544 "A storage place should be supported if its size is equal to the 545 ``Size`` of the component subtype, and it starts and ends on a 546 boundary that obeys the ``Alignment`` of the component subtype." 547 548Followed. 549 550 "If the default bit ordering applies to the declaration of a given type, 551 then for a component whose subtype's ``Size`` is less than the word 552 size, any storage place that does not cross an aligned word boundary 553 should be supported." 554 555Followed. 556 557 "An implementation may reserve a storage place for the tag field of a 558 tagged type, and disallow other components from overlapping that place." 559 560Followed. The storage place for the tag field is the beginning of the tagged 561record, and its size is Address'Size. GNAT will reject an explicit component 562clause for the tag field. 563 564 "An implementation need not support a *component_clause* for a 565 component of an extension part if the storage place is not after the 566 storage places of all components of the parent type, whether or not 567 those storage places had been specified." 568 569Followed. The above advice on record representation clauses is followed, 570and all mentioned features are implemented. 571 572.. index:: Storage place attributes 573 574RM 13.5.2(5): Storage Place Attributes 575====================================== 576 577 "If a component is represented using some form of pointer (such as an 578 offset) to the actual data of the component, and this data is contiguous 579 with the rest of the object, then the storage place attributes should 580 reflect the place of the actual data, not the pointer. If a component is 581 allocated discontinuously from the rest of the object, then a warning 582 should be generated upon reference to one of its storage place 583 attributes." 584 585Followed. There are no such components in GNAT. 586 587.. index:: Bit ordering 588 589RM 13.5.3(7-8): Bit Ordering 590============================ 591 592 "The recommended level of support for the non-default bit ordering is: 593 594 If ``Word_Size`` = ``Storage_Unit``, then the implementation 595 should support the non-default bit ordering in addition to the default 596 bit ordering." 597 598Followed. Word size does not equal storage size in this implementation. 599Thus non-default bit ordering is not supported. 600 601.. index:: Address, as private type 602 603RM 13.7(37): Address as Private 604=============================== 605 606 "`Address` should be of a private type." 607 608Followed. 609 610.. index:: Operations, on ``Address`` 611 612.. index:: Address, operations of 613 614RM 13.7.1(16): Address Operations 615================================= 616 617 "Operations in ``System`` and its children should reflect the target 618 environment semantics as closely as is reasonable. For example, on most 619 machines, it makes sense for address arithmetic to 'wrap around'. 620 Operations that do not make sense should raise ``Program_Error``." 621 622Followed. Address arithmetic is modular arithmetic that wraps around. No 623operation raises ``Program_Error``, since all operations make sense. 624 625.. index:: Unchecked conversion 626 627RM 13.9(14-17): Unchecked Conversion 628==================================== 629 630 "The ``Size`` of an array object should not include its bounds; hence, 631 the bounds should not be part of the converted data." 632 633Followed. 634 635 "The implementation should not generate unnecessary run-time checks to 636 ensure that the representation of ``S`` is a representation of the 637 target type. It should take advantage of the permission to return by 638 reference when possible. Restrictions on unchecked conversions should be 639 avoided unless required by the target environment." 640 641Followed. There are no restrictions on unchecked conversion. A warning is 642generated if the source and target types do not have the same size since 643the semantics in this case may be target dependent. 644 645 "The recommended level of support for unchecked conversions is: 646 647 Unchecked conversions should be supported and should be reversible in 648 the cases where this clause defines the result. To enable meaningful use 649 of unchecked conversion, a contiguous representation should be used for 650 elementary subtypes, for statically constrained array subtypes whose 651 component subtype is one of the subtypes described in this paragraph, 652 and for record subtypes without discriminants whose component subtypes 653 are described in this paragraph." 654 655Followed. 656 657.. index:: Heap usage, implicit 658 659RM 13.11(23-25): Implicit Heap Usage 660==================================== 661 662 "An implementation should document any cases in which it dynamically 663 allocates heap storage for a purpose other than the evaluation of an 664 allocator." 665 666Followed, the only other points at which heap storage is dynamically 667allocated are as follows: 668 669* 670 At initial elaboration time, to allocate dynamically sized global 671 objects. 672 673* 674 To allocate space for a task when a task is created. 675 676* 677 To extend the secondary stack dynamically when needed. The secondary 678 stack is used for returning variable length results. 679 680.. 681 682 "A default (implementation-provided) storage pool for an 683 access-to-constant type should not have overhead to support deallocation of 684 individual objects." 685 686Followed. 687 688 "A storage pool for an anonymous access type should be created at the 689 point of an allocator for the type, and be reclaimed when the designated 690 object becomes inaccessible." 691 692Followed. 693 694.. index:: Unchecked deallocation 695 696RM 13.11.2(17): Unchecked Deallocation 697====================================== 698 699 "For a standard storage pool, ``Free`` should actually reclaim the 700 storage." 701 702Followed. 703 704.. index:: Stream oriented attributes 705 706RM 13.13.2(17): Stream Oriented Attributes 707========================================== 708 709 "If a stream element is the same size as a storage element, then the 710 normal in-memory representation should be used by ``Read`` and 711 ``Write`` for scalar objects. Otherwise, ``Read`` and ``Write`` 712 should use the smallest number of stream elements needed to represent 713 all values in the base range of the scalar type." 714 715Followed. By default, GNAT uses the interpretation suggested by AI-195, 716which specifies using the size of the first subtype. 717However, such an implementation is based on direct binary 718representations and is therefore target- and endianness-dependent. 719To address this issue, GNAT also supplies an alternate implementation 720of the stream attributes ``Read`` and ``Write``, 721which uses the target-independent XDR standard representation 722for scalar types. 723 724.. index:: XDR representation 725 726.. index:: Read attribute 727 728.. index:: Write attribute 729 730.. index:: Stream oriented attributes 731 732The XDR implementation is provided as an alternative body of the 733``System.Stream_Attributes`` package, in the file 734:file:`s-stratt-xdr.adb` in the GNAT library. 735There is no :file:`s-stratt-xdr.ads` file. 736In order to install the XDR implementation, do the following: 737 738* Replace the default implementation of the 739 ``System.Stream_Attributes`` package with the XDR implementation. 740 For example on a Unix platform issue the commands: 741 742 .. code-block:: sh 743 744 $ mv s-stratt.adb s-stratt-default.adb 745 $ mv s-stratt-xdr.adb s-stratt.adb 746 747 748* 749 Rebuild the GNAT run-time library as documented in 750 the *GNAT and Libraries* section of the :title:`GNAT User's Guide`. 751 752RM A.1(52): Names of Predefined Numeric Types 753============================================= 754 755 "If an implementation provides additional named predefined integer types, 756 then the names should end with ``Integer`` as in 757 ``Long_Integer``. If an implementation provides additional named 758 predefined floating point types, then the names should end with 759 ``Float`` as in ``Long_Float``." 760 761Followed. 762 763.. index:: Ada.Characters.Handling 764 765RM A.3.2(49): ``Ada.Characters.Handling`` 766========================================= 767 768 "If an implementation provides a localized definition of ``Character`` 769 or ``Wide_Character``, then the effects of the subprograms in 770 ``Characters.Handling`` should reflect the localizations. 771 See also 3.5.2." 772 773Followed. GNAT provides no such localized definitions. 774 775.. index:: Bounded-length strings 776 777RM A.4.4(106): Bounded-Length String Handling 778============================================= 779 780 "Bounded string objects should not be implemented by implicit pointers 781 and dynamic allocation." 782 783Followed. No implicit pointers or dynamic allocation are used. 784 785.. index:: Random number generation 786 787RM A.5.2(46-47): Random Number Generation 788========================================= 789 790 "Any storage associated with an object of type ``Generator`` should be 791 reclaimed on exit from the scope of the object." 792 793Followed. 794 795 "If the generator period is sufficiently long in relation to the number 796 of distinct initiator values, then each possible value of 797 ``Initiator`` passed to ``Reset`` should initiate a sequence of 798 random numbers that does not, in a practical sense, overlap the sequence 799 initiated by any other value. If this is not possible, then the mapping 800 between initiator values and generator states should be a rapidly 801 varying function of the initiator value." 802 803Followed. The generator period is sufficiently long for the first 804condition here to hold true. 805 806.. index:: Get_Immediate 807 808RM A.10.7(23): ``Get_Immediate`` 809================================ 810 811 "The ``Get_Immediate`` procedures should be implemented with 812 unbuffered input. For a device such as a keyboard, input should be 813 available if a key has already been typed, whereas for a disk 814 file, input should always be available except at end of file. For a file 815 associated with a keyboard-like device, any line-editing features of the 816 underlying operating system should be disabled during the execution of 817 ``Get_Immediate``." 818 819Followed on all targets except VxWorks. For VxWorks, there is no way to 820provide this functionality that does not result in the input buffer being 821flushed before the ``Get_Immediate`` call. A special unit 822``Interfaces.Vxworks.IO`` is provided that contains routines to enable 823this functionality. 824 825.. index:: Export 826 827RM B.1(39-41): Pragma ``Export`` 828================================ 829 830 "If an implementation supports pragma ``Export`` to a given language, 831 then it should also allow the main subprogram to be written in that 832 language. It should support some mechanism for invoking the elaboration 833 of the Ada library units included in the system, and for invoking the 834 finalization of the environment task. On typical systems, the 835 recommended mechanism is to provide two subprograms whose link names are 836 ``adainit`` and ``adafinal``. ``adainit`` should contain the 837 elaboration code for library units. ``adafinal`` should contain the 838 finalization code. These subprograms should have no effect the second 839 and subsequent time they are called." 840 841Followed. 842 843 "Automatic elaboration of pre-elaborated packages should be 844 provided when pragma ``Export`` is supported." 845 846Followed when the main program is in Ada. If the main program is in a 847foreign language, then 848``adainit`` must be called to elaborate pre-elaborated 849packages. 850 851 "For each supported convention *L* other than ``Intrinsic``, an 852 implementation should support ``Import`` and ``Export`` pragmas 853 for objects of *L*\ -compatible types and for subprograms, and pragma 854 `Convention` for *L*\ -eligible types and for subprograms, 855 presuming the other language has corresponding features. Pragma 856 ``Convention`` need not be supported for scalar types." 857 858Followed. 859 860.. index:: Package Interfaces 861 862.. index:: Interfaces 863 864RM B.2(12-13): Package ``Interfaces`` 865===================================== 866 867 "For each implementation-defined convention identifier, there should be a 868 child package of package Interfaces with the corresponding name. This 869 package should contain any declarations that would be useful for 870 interfacing to the language (implementation) represented by the 871 convention. Any declarations useful for interfacing to any language on 872 the given hardware architecture should be provided directly in 873 ``Interfaces``." 874 875Followed. 876 877 "An implementation supporting an interface to C, COBOL, or Fortran should 878 provide the corresponding package or packages described in the following 879 clauses." 880 881Followed. GNAT provides all the packages described in this section. 882 883.. index:: C, interfacing with 884 885RM B.3(63-71): Interfacing with C 886================================= 887 888 "An implementation should support the following interface correspondences 889 between Ada and C." 890 891Followed. 892 893 "An Ada procedure corresponds to a void-returning C function." 894 895Followed. 896 897 "An Ada function corresponds to a non-void C function." 898 899Followed. 900 901 "An Ada ``in`` scalar parameter is passed as a scalar argument to a C 902 function." 903 904Followed. 905 906 "An Ada ``in`` parameter of an access-to-object type with designated 907 type ``T`` is passed as a ``t*`` argument to a C function, 908 where ``t`` is the C type corresponding to the Ada type ``T``." 909 910Followed. 911 912 "An Ada access ``T`` parameter, or an Ada ``out`` or ``in out`` 913 parameter of an elementary type ``T``, is passed as a ``t*`` 914 argument to a C function, where ``t`` is the C type corresponding to 915 the Ada type ``T``. In the case of an elementary ``out`` or 916 ``in out`` parameter, a pointer to a temporary copy is used to 917 preserve by-copy semantics." 918 919Followed. 920 921 "An Ada parameter of a record type ``T``, of any mode, is passed as a 922 ``t*`` argument to a C function, where ``t`` is the C 923 structure corresponding to the Ada type ``T``." 924 925Followed. This convention may be overridden by the use of the C_Pass_By_Copy 926pragma, or Convention, or by explicitly specifying the mechanism for a given 927call using an extended import or export pragma. 928 929 "An Ada parameter of an array type with component type ``T``, of any 930 mode, is passed as a ``t*`` argument to a C function, where 931 ``t`` is the C type corresponding to the Ada type ``T``." 932 933Followed. 934 935 "An Ada parameter of an access-to-subprogram type is passed as a pointer 936 to a C function whose prototype corresponds to the designated 937 subprogram's specification." 938 939Followed. 940 941.. index:: COBOL, interfacing with 942 943RM B.4(95-98): Interfacing with COBOL 944===================================== 945 946 "An Ada implementation should support the following interface 947 correspondences between Ada and COBOL." 948 949Followed. 950 951 "An Ada access ``T`` parameter is passed as a ``BY REFERENCE`` data item of 952 the COBOL type corresponding to ``T``." 953 954Followed. 955 956 "An Ada in scalar parameter is passed as a ``BY CONTENT`` data item of 957 the corresponding COBOL type." 958 959Followed. 960 961 "Any other Ada parameter is passed as a ``BY REFERENCE`` data item of the 962 COBOL type corresponding to the Ada parameter type; for scalars, a local 963 copy is used if necessary to ensure by-copy semantics." 964 965Followed. 966 967.. index:: Fortran, interfacing with 968 969RM B.5(22-26): Interfacing with Fortran 970======================================= 971 972 "An Ada implementation should support the following interface 973 correspondences between Ada and Fortran:" 974 975Followed. 976 977 "An Ada procedure corresponds to a Fortran subroutine." 978 979Followed. 980 981 "An Ada function corresponds to a Fortran function." 982 983Followed. 984 985 "An Ada parameter of an elementary, array, or record type ``T`` is 986 passed as a ``T`` argument to a Fortran procedure, where ``T`` is 987 the Fortran type corresponding to the Ada type ``T``, and where the 988 INTENT attribute of the corresponding dummy argument matches the Ada 989 formal parameter mode; the Fortran implementation's parameter passing 990 conventions are used. For elementary types, a local copy is used if 991 necessary to ensure by-copy semantics." 992 993Followed. 994 995 "An Ada parameter of an access-to-subprogram type is passed as a 996 reference to a Fortran procedure whose interface corresponds to the 997 designated subprogram's specification." 998 999Followed. 1000 1001.. index:: Machine operations 1002 1003RM C.1(3-5): Access to Machine Operations 1004========================================= 1005 1006 "The machine code or intrinsic support should allow access to all 1007 operations normally available to assembly language programmers for the 1008 target environment, including privileged instructions, if any." 1009 1010Followed. 1011 1012 "The interfacing pragmas (see Annex B) should support interface to 1013 assembler; the default assembler should be associated with the 1014 convention identifier ``Assembler``." 1015 1016Followed. 1017 1018 "If an entity is exported to assembly language, then the implementation 1019 should allocate it at an addressable location, and should ensure that it 1020 is retained by the linking process, even if not otherwise referenced 1021 from the Ada code. The implementation should assume that any call to a 1022 machine code or assembler subprogram is allowed to read or update every 1023 object that is specified as exported." 1024 1025Followed. 1026 1027RM C.1(10-16): Access to Machine Operations 1028=========================================== 1029 1030 "The implementation should ensure that little or no overhead is 1031 associated with calling intrinsic and machine-code subprograms." 1032 1033Followed for both intrinsics and machine-code subprograms. 1034 1035 "It is recommended that intrinsic subprograms be provided for convenient 1036 access to any machine operations that provide special capabilities or 1037 efficiency and that are not otherwise available through the language 1038 constructs." 1039 1040Followed. A full set of machine operation intrinsic subprograms is provided. 1041 1042 "Atomic read-modify-write operations---e.g., test and set, compare and 1043 swap, decrement and test, enqueue/dequeue." 1044 1045Followed on any target supporting such operations. 1046 1047 "Standard numeric functions---e.g.:, sin, log." 1048 1049Followed on any target supporting such operations. 1050 1051 "String manipulation operations---e.g.:, translate and test." 1052 1053Followed on any target supporting such operations. 1054 1055 "Vector operations---e.g.:, compare vector against thresholds." 1056 1057Followed on any target supporting such operations. 1058 1059 "Direct operations on I/O ports." 1060 1061Followed on any target supporting such operations. 1062 1063.. index:: Interrupt support 1064 1065RM C.3(28): Interrupt Support 1066============================= 1067 1068 "If the ``Ceiling_Locking`` policy is not in effect, the 1069 implementation should provide means for the application to specify which 1070 interrupts are to be blocked during protected actions, if the underlying 1071 system allows for a finer-grain control of interrupt blocking." 1072 1073Followed. The underlying system does not allow for finer-grain control 1074of interrupt blocking. 1075 1076.. index:: Protected procedure handlers 1077 1078RM C.3.1(20-21): Protected Procedure Handlers 1079============================================= 1080 1081 "Whenever possible, the implementation should allow interrupt handlers to 1082 be called directly by the hardware." 1083 1084Followed on any target where the underlying operating system permits 1085such direct calls. 1086 1087 "Whenever practical, violations of any 1088 implementation-defined restrictions should be detected before run time." 1089 1090Followed. Compile time warnings are given when possible. 1091 1092.. index:: Package ``Interrupts`` 1093 1094.. index:: Interrupts 1095 1096RM C.3.2(25): Package ``Interrupts`` 1097==================================== 1098 1099 "If implementation-defined forms of interrupt handler procedures are 1100 supported, such as protected procedures with parameters, then for each 1101 such form of a handler, a type analogous to ``Parameterless_Handler`` 1102 should be specified in a child package of ``Interrupts``, with the 1103 same operations as in the predefined package Interrupts." 1104 1105Followed. 1106 1107.. index:: Pre-elaboration requirements 1108 1109RM C.4(14): Pre-elaboration Requirements 1110======================================== 1111 1112 "It is recommended that pre-elaborated packages be implemented in such a 1113 way that there should be little or no code executed at run time for the 1114 elaboration of entities not already covered by the Implementation 1115 Requirements." 1116 1117Followed. Executable code is generated in some cases, e.g., loops 1118to initialize large arrays. 1119 1120RM C.5(8): Pragma ``Discard_Names`` 1121=================================== 1122 1123 "If the pragma applies to an entity, then the implementation should 1124 reduce the amount of storage used for storing names associated with that 1125 entity." 1126 1127Followed. 1128 1129.. index:: Package Task_Attributes 1130 1131.. index:: Task_Attributes 1132 1133RM C.7.2(30): The Package Task_Attributes 1134========================================= 1135 1136 "Some implementations are targeted to domains in which memory use at run 1137 time must be completely deterministic. For such implementations, it is 1138 recommended that the storage for task attributes will be pre-allocated 1139 statically and not from the heap. This can be accomplished by either 1140 placing restrictions on the number and the size of the task's 1141 attributes, or by using the pre-allocated storage for the first ``N`` 1142 attribute objects, and the heap for the others. In the latter case, 1143 ``N`` should be documented." 1144 1145Not followed. This implementation is not targeted to such a domain. 1146 1147.. index:: Locking Policies 1148 1149RM D.3(17): Locking Policies 1150============================ 1151 1152 "The implementation should use names that end with ``_Locking`` for 1153 locking policies defined by the implementation." 1154 1155Followed. Two implementation-defined locking policies are defined, 1156whose names (``Inheritance_Locking`` and 1157``Concurrent_Readers_Locking``) follow this suggestion. 1158 1159.. index:: Entry queuing policies 1160 1161RM D.4(16): Entry Queuing Policies 1162================================== 1163 1164 "Names that end with ``_Queuing`` should be used 1165 for all implementation-defined queuing policies." 1166 1167Followed. No such implementation-defined queuing policies exist. 1168 1169.. index:: Preemptive abort 1170 1171RM D.6(9-10): Preemptive Abort 1172============================== 1173 1174 "Even though the *abort_statement* is included in the list of 1175 potentially blocking operations (see 9.5.1), it is recommended that this 1176 statement be implemented in a way that never requires the task executing 1177 the *abort_statement* to block." 1178 1179Followed. 1180 1181 "On a multi-processor, the delay associated with aborting a task on 1182 another processor should be bounded; the implementation should use 1183 periodic polling, if necessary, to achieve this." 1184 1185Followed. 1186 1187.. index:: Tasking restrictions 1188 1189RM D.7(21): Tasking Restrictions 1190================================ 1191 1192 "When feasible, the implementation should take advantage of the specified 1193 restrictions to produce a more efficient implementation." 1194 1195GNAT currently takes advantage of these restrictions by providing an optimized 1196run time when the Ravenscar profile and the GNAT restricted run time set 1197of restrictions are specified. See pragma ``Profile (Ravenscar)`` and 1198pragma ``Profile (Restricted)`` for more details. 1199 1200.. index:: Time, monotonic 1201 1202RM D.8(47-49): Monotonic Time 1203============================= 1204 1205 "When appropriate, implementations should provide configuration 1206 mechanisms to change the value of ``Tick``." 1207 1208Such configuration mechanisms are not appropriate to this implementation 1209and are thus not supported. 1210 1211 "It is recommended that ``Calendar.Clock`` and ``Real_Time.Clock`` 1212 be implemented as transformations of the same time base." 1213 1214Followed. 1215 1216 1217 "It is recommended that the best time base which exists in 1218 the underlying system be available to the application through 1219 ``Clock``. `Best` may mean highest accuracy or largest range." 1220 1221Followed. 1222 1223.. index:: Partition communication subsystem 1224 1225.. index:: PCS 1226 1227RM E.5(28-29): Partition Communication Subsystem 1228================================================ 1229 1230 "Whenever possible, the PCS on the called partition should allow for 1231 multiple tasks to call the RPC-receiver with different messages and 1232 should allow them to block until the corresponding subprogram body 1233 returns." 1234 1235Followed by GLADE, a separately supplied PCS that can be used with 1236GNAT. 1237 1238 "The ``Write`` operation on a stream of type ``Params_Stream_Type`` 1239 should raise ``Storage_Error`` if it runs out of space trying to 1240 write the ``Item`` into the stream." 1241 1242Followed by GLADE, a separately supplied PCS that can be used with 1243GNAT. 1244 1245.. index:: COBOL support 1246 1247RM F(7): COBOL Support 1248====================== 1249 1250 "If COBOL (respectively, C) is widely supported in the target 1251 environment, implementations supporting the Information Systems Annex 1252 should provide the child package ``Interfaces.COBOL`` (respectively, 1253 ``Interfaces.C``) specified in Annex B and should support a 1254 ``convention_identifier`` of COBOL (respectively, C) in the interfacing 1255 pragmas (see Annex B), thus allowing Ada programs to interface with 1256 programs written in that language." 1257 1258Followed. 1259 1260.. index:: Decimal radix support 1261 1262RM F.1(2): Decimal Radix Support 1263================================ 1264 1265 "Packed decimal should be used as the internal representation for objects 1266 of subtype ``S`` when ``S``'Machine_Radix = 10." 1267 1268Not followed. GNAT ignores ``S``'Machine_Radix and always uses binary 1269representations. 1270 1271.. index:: Numerics 1272 1273RM G: Numerics 1274============== 1275 1276 "If Fortran (respectively, C) is widely supported in the target 1277 environment, implementations supporting the Numerics Annex 1278 should provide the child package ``Interfaces.Fortran`` (respectively, 1279 ``Interfaces.C``) specified in Annex B and should support a 1280 ``convention_identifier`` of Fortran (respectively, C) in the interfacing 1281 pragmas (see Annex B), thus allowing Ada programs to interface with 1282 programs written in that language." 1283 1284Followed. 1285 1286.. index:: Complex types 1287 1288RM G.1.1(56-58): Complex Types 1289============================== 1290 1291 "Because the usual mathematical meaning of multiplication of a complex 1292 operand and a real operand is that of the scaling of both components of 1293 the former by the latter, an implementation should not perform this 1294 operation by first promoting the real operand to complex type and then 1295 performing a full complex multiplication. In systems that, in the 1296 future, support an Ada binding to IEC 559:1989, the latter technique 1297 will not generate the required result when one of the components of the 1298 complex operand is infinite. (Explicit multiplication of the infinite 1299 component by the zero component obtained during promotion yields a NaN 1300 that propagates into the final result.) Analogous advice applies in the 1301 case of multiplication of a complex operand and a pure-imaginary 1302 operand, and in the case of division of a complex operand by a real or 1303 pure-imaginary operand." 1304 1305Not followed. 1306 1307 "Similarly, because the usual mathematical meaning of addition of a 1308 complex operand and a real operand is that the imaginary operand remains 1309 unchanged, an implementation should not perform this operation by first 1310 promoting the real operand to complex type and then performing a full 1311 complex addition. In implementations in which the ``Signed_Zeros`` 1312 attribute of the component type is ``True`` (and which therefore 1313 conform to IEC 559:1989 in regard to the handling of the sign of zero in 1314 predefined arithmetic operations), the latter technique will not 1315 generate the required result when the imaginary component of the complex 1316 operand is a negatively signed zero. (Explicit addition of the negative 1317 zero to the zero obtained during promotion yields a positive zero.) 1318 Analogous advice applies in the case of addition of a complex operand 1319 and a pure-imaginary operand, and in the case of subtraction of a 1320 complex operand and a real or pure-imaginary operand." 1321 1322Not followed. 1323 1324 "Implementations in which ``Real'Signed_Zeros`` is ``True`` should 1325 attempt to provide a rational treatment of the signs of zero results and 1326 result components. As one example, the result of the ``Argument`` 1327 function should have the sign of the imaginary component of the 1328 parameter ``X`` when the point represented by that parameter lies on 1329 the positive real axis; as another, the sign of the imaginary component 1330 of the ``Compose_From_Polar`` function should be the same as 1331 (respectively, the opposite of) that of the ``Argument`` parameter when that 1332 parameter has a value of zero and the ``Modulus`` parameter has a 1333 nonnegative (respectively, negative) value." 1334 1335Followed. 1336 1337.. index:: Complex elementary functions 1338 1339RM G.1.2(49): Complex Elementary Functions 1340========================================== 1341 1342 "Implementations in which ``Complex_Types.Real'Signed_Zeros`` is 1343 ``True`` should attempt to provide a rational treatment of the signs 1344 of zero results and result components. For example, many of the complex 1345 elementary functions have components that are odd functions of one of 1346 the parameter components; in these cases, the result component should 1347 have the sign of the parameter component at the origin. Other complex 1348 elementary functions have zero components whose sign is opposite that of 1349 a parameter component at the origin, or is always positive or always 1350 negative." 1351 1352Followed. 1353 1354.. index:: Accuracy requirements 1355 1356RM G.2.4(19): Accuracy Requirements 1357=================================== 1358 1359 "The versions of the forward trigonometric functions without a 1360 ``Cycle`` parameter should not be implemented by calling the 1361 corresponding version with a ``Cycle`` parameter of 1362 ``2.0*Numerics.Pi``, since this will not provide the required 1363 accuracy in some portions of the domain. For the same reason, the 1364 version of ``Log`` without a ``Base`` parameter should not be 1365 implemented by calling the corresponding version with a ``Base`` 1366 parameter of ``Numerics.e``." 1367 1368Followed. 1369 1370.. index:: Complex arithmetic accuracy 1371 1372.. index:: Accuracy, complex arithmetic 1373 1374RM G.2.6(15): Complex Arithmetic Accuracy 1375========================================= 1376 1377 "The version of the ``Compose_From_Polar`` function without a 1378 ``Cycle`` parameter should not be implemented by calling the 1379 corresponding version with a ``Cycle`` parameter of 1380 ``2.0*Numerics.Pi``, since this will not provide the required 1381 accuracy in some portions of the domain." 1382 1383Followed. 1384 1385.. index:: Sequential elaboration policy 1386 1387RM H.6(15/2): Pragma Partition_Elaboration_Policy 1388================================================= 1389 1390 "If the partition elaboration policy is ``Sequential`` and the 1391 Environment task becomes permanently blocked during elaboration then the 1392 partition is deadlocked and it is recommended that the partition be 1393 immediately terminated." 1394 1395Not followed. 1396