Debian Codegraph @

gcc/ada/doc/gnat_rm/implementation_advice.rst

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