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.
306 For 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
321 Followed. Size Clauses are not permitted on nonstatic components, as
322 described 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
328 Followed.
329
330 .. index:: Packed types
331
332 RM 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
349 Followed. Tight packing of arrays is supported for all component sizes
350 up to 64-bits. If the array component size is 1 (that is to say, if
351 the component is a boolean type or an enumeration type with two values)
352 then values of the type are implicitly initialized to zero. This
353 happens both for objects of the packed type, and for objects that have a
354 subcomponent of the packed type.
355
356
357 "An implementation should support Address clauses for imported
358 subprograms."
359
360 Followed.
361
362 .. index:: Address clauses
363
364 RM 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
370 Followed.
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
378 Followed. A valid address will be produced even if none of those
379 conditions have been met. If necessary, the object is forced into
380 memory to ensure the address is valid.
381
382 "An implementation should support ``Address`` clauses for imported
383 subprograms."
384
385 Followed.
386
387 "Objects (including subcomponents) that are aliased or of a by-reference
388 type should be allocated on storage element boundaries."
389
390 Followed.
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
396 Followed.
397
398 .. index:: Alignment clauses
399
400 RM 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
410 Followed.
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
416 Followed.
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
422 Followed.
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
429 Followed.
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
436 Followed.
437
438 .. index:: Size clauses
439
440 RM 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
451 Followed.
452
453 RM 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
463 Followed.
464
465 "`Size` clause on a composite subtype should not affect the
466 internal layout of components."
467
468 Followed. But note that this can be overridden by use of the implementation
469 pragma 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
480 Followed.
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
486 Followed.
487
488 .. index:: Component_Size clauses
489
490 RM 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
499 Followed.
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
509 Followed.
510
511 .. index:: Enumeration representation clauses
512
513 .. index:: Representation clauses, enumeration
514
515 RM 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
525 Followed.
526
527 .. index:: Record representation clauses
528
529 .. index:: Representation clauses, records
530
531 RM 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
542 Followed.
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
548 Followed.
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
555 Followed.
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
560 Followed. The storage place for the tag field is the beginning of the tagged
561 record, and its size is Address'Size. GNAT will reject an explicit component
562 clause 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
569 Followed. The above advice on record representation clauses is followed,
570 and all mentioned features are implemented.
571
572 .. index:: Storage place attributes
573
574 RM 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
585 Followed. There are no such components in GNAT.
586
587 .. index:: Bit ordering
588
589 RM 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
598 Followed. Word size does not equal storage size in this implementation.
599 Thus non-default bit ordering is not supported.
600
601 .. index:: Address, as private type
602
603 RM 13.7(37): Address as Private
604 ===============================
605
606 "`Address` should be of a private type."
607
608 Followed.
609
610 .. index:: Operations, on ``Address``
611
612 .. index:: Address, operations of
613
614 RM 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
622 Followed. Address arithmetic is modular arithmetic that wraps around. No
623 operation raises ``Program_Error``, since all operations make sense.
624
625 .. index:: Unchecked conversion
626
627 RM 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
633 Followed.
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
641 Followed. There are no restrictions on unchecked conversion. A warning is
642 generated if the source and target types do not have the same size since
643 the 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
655 Followed.
656
657 .. index:: Heap usage, implicit
658
659 RM 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
666 Followed, the only other points at which heap storage is dynamically
667 allocated 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
686 Followed.
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
692 Followed.
693
694 .. index:: Unchecked deallocation
695
696 RM 13.11.2(17): Unchecked Deallocation
697 ======================================
698
699 "For a standard storage pool, ``Free`` should actually reclaim the
700 storage."
701
702 Followed.
703
704 .. index:: Stream oriented attributes
705
706 RM 13.13.2(1.6): Stream Oriented Attributes
707 ===========================================
708
709 "If not specified, the value of Stream_Size for an elementary type
710 should be the number of bits that corresponds to the minimum number of
711 stream elements required by the first subtype of the type, rounded up
712 to the nearest factor or multiple of the word size that is also a
713 multiple of the stream element size."
714
715 Followed, except that the number of stream elements is 1, 2, 3, 4 or 8.
716 The Stream_Size may be used to override the default choice.
717
718 The default implementation is based on direct binary representations and is
719 therefore target- and endianness-dependent. To address this issue, GNAT also
720 supplies an alternate implementation of the stream attributes ``Read`` and
721 ``Write``, which uses the target-independent XDR standard representation for
722 scalar types. This XDR alternative can be enabled via the binder switch -xdr.
723
724 .. index:: XDR representation
725 .. index:: Read attribute
726 .. index:: Write attribute
727 .. index:: Stream oriented attributes
728
729 RM A.1(52): Names of Predefined Numeric Types
730 =============================================
731
732 "If an implementation provides additional named predefined integer types,
733 then the names should end with ``Integer`` as in
734 ``Long_Integer``. If an implementation provides additional named
735 predefined floating point types, then the names should end with
736 ``Float`` as in ``Long_Float``."
737
738 Followed.
739
740 .. index:: Ada.Characters.Handling
741
742 RM A.3.2(49): ``Ada.Characters.Handling``
743 =========================================
744
745 "If an implementation provides a localized definition of ``Character``
746 or ``Wide_Character``, then the effects of the subprograms in
747 ``Characters.Handling`` should reflect the localizations.
748 See also 3.5.2."
749
750 Followed. GNAT provides no such localized definitions.
751
752 .. index:: Bounded-length strings
753
754 RM A.4.4(106): Bounded-Length String Handling
755 =============================================
756
757 "Bounded string objects should not be implemented by implicit pointers
758 and dynamic allocation."
759
760 Followed. No implicit pointers or dynamic allocation are used.
761
762 .. index:: Random number generation
763
764 RM A.5.2(46-47): Random Number Generation
765 =========================================
766
767 "Any storage associated with an object of type ``Generator`` should be
768 reclaimed on exit from the scope of the object."
769
770 Followed.
771
772 "If the generator period is sufficiently long in relation to the number
773 of distinct initiator values, then each possible value of
774 ``Initiator`` passed to ``Reset`` should initiate a sequence of
775 random numbers that does not, in a practical sense, overlap the sequence
776 initiated by any other value. If this is not possible, then the mapping
777 between initiator values and generator states should be a rapidly
778 varying function of the initiator value."
779
780 Followed. The generator period is sufficiently long for the first
781 condition here to hold true.
782
783 .. index:: Get_Immediate
784
785 RM A.10.7(23): ``Get_Immediate``
786 ================================
787
788 "The ``Get_Immediate`` procedures should be implemented with
789 unbuffered input. For a device such as a keyboard, input should be
790 available if a key has already been typed, whereas for a disk
791 file, input should always be available except at end of file. For a file
792 associated with a keyboard-like device, any line-editing features of the
793 underlying operating system should be disabled during the execution of
794 ``Get_Immediate``."
795
796 Followed on all targets except VxWorks. For VxWorks, there is no way to
797 provide this functionality that does not result in the input buffer being
798 flushed before the ``Get_Immediate`` call. A special unit
799 ``Interfaces.Vxworks.IO`` is provided that contains routines to enable
800 this functionality.
801
802 .. index:: Containers
803
804 RM A.18: ``Containers``
805 ================================
806
807 All implementation advice pertaining to Ada.Containers and its
808 child units (that is, all implementation advice occurring within
809 section A.18 and its subsections) is followed except for A.18.24(17):
810
811 "Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. "
812
813 The implementations of the two Reference_Preserving_Key functions of
814 the generic package Ada.Containers.Bounded_Ordered_Sets each currently make
815 use of dynamic allocation; other operations on bounded ordered set objects
816 follow the implementation advice.
817
818 .. index:: Export
819
820 RM B.1(39-41): Pragma ``Export``
821 ================================
822
823 "If an implementation supports pragma ``Export`` to a given language,
824 then it should also allow the main subprogram to be written in that
825 language. It should support some mechanism for invoking the elaboration
826 of the Ada library units included in the system, and for invoking the
827 finalization of the environment task. On typical systems, the
828 recommended mechanism is to provide two subprograms whose link names are
829 ``adainit`` and ``adafinal``. ``adainit`` should contain the
830 elaboration code for library units. ``adafinal`` should contain the
831 finalization code. These subprograms should have no effect the second
832 and subsequent time they are called."
833
834 Followed.
835
836 "Automatic elaboration of pre-elaborated packages should be
837 provided when pragma ``Export`` is supported."
838
839 Followed when the main program is in Ada. If the main program is in a
840 foreign language, then
841 ``adainit`` must be called to elaborate pre-elaborated
842 packages.
843
844 "For each supported convention *L* other than ``Intrinsic``, an
845 implementation should support ``Import`` and ``Export`` pragmas
846 for objects of *L*\ -compatible types and for subprograms, and pragma
847 `Convention` for *L*\ -eligible types and for subprograms,
848 presuming the other language has corresponding features. Pragma
849 ``Convention`` need not be supported for scalar types."
850
851 Followed.
852
853 .. index:: Package Interfaces
854
855 .. index:: Interfaces
856
857 RM B.2(12-13): Package ``Interfaces``
858 =====================================
859
860 "For each implementation-defined convention identifier, there should be a
861 child package of package Interfaces with the corresponding name. This
862 package should contain any declarations that would be useful for
863 interfacing to the language (implementation) represented by the
864 convention. Any declarations useful for interfacing to any language on
865 the given hardware architecture should be provided directly in
866 ``Interfaces``."
867
868 Followed.
869
870 "An implementation supporting an interface to C, COBOL, or Fortran should
871 provide the corresponding package or packages described in the following
872 clauses."
873
874 Followed. GNAT provides all the packages described in this section.
875
876 .. index:: C, interfacing with
877
878 RM B.3(63-71): Interfacing with C
879 =================================
880
881 "An implementation should support the following interface correspondences
882 between Ada and C."
883
884 Followed.
885
886 "An Ada procedure corresponds to a void-returning C function."
887
888 Followed.
889
890 "An Ada function corresponds to a non-void C function."
891
892 Followed.
893
894 "An Ada ``in`` scalar parameter is passed as a scalar argument to a C
895 function."
896
897 Followed.
898
899 "An Ada ``in`` parameter of an access-to-object type with designated
900 type ``T`` is passed as a ``t*`` argument to a C function,
901 where ``t`` is the C type corresponding to the Ada type ``T``."
902
903 Followed.
904
905 "An Ada access ``T`` parameter, or an Ada ``out`` or ``in out``
906 parameter of an elementary type ``T``, is passed as a ``t*``
907 argument to a C function, where ``t`` is the C type corresponding to
908 the Ada type ``T``. In the case of an elementary ``out`` or
909 ``in out`` parameter, a pointer to a temporary copy is used to
910 preserve by-copy semantics."
911
912 Followed.
913
914 "An Ada parameter of a record type ``T``, of any mode, is passed as a
915 ``t*`` argument to a C function, where ``t`` is the C
916 structure corresponding to the Ada type ``T``."
917
918 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
919 pragma, or Convention, or by explicitly specifying the mechanism for a given
920 call using an extended import or export pragma.
921
922 "An Ada parameter of an array type with component type ``T``, of any
923 mode, is passed as a ``t*`` argument to a C function, where
924 ``t`` is the C type corresponding to the Ada type ``T``."
925
926 Followed.
927
928 "An Ada parameter of an access-to-subprogram type is passed as a pointer
929 to a C function whose prototype corresponds to the designated
930 subprogram's specification."
931
932 Followed.
933
934 .. index:: COBOL, interfacing with
935
936 RM B.4(95-98): Interfacing with COBOL
937 =====================================
938
939 "An Ada implementation should support the following interface
940 correspondences between Ada and COBOL."
941
942 Followed.
943
944 "An Ada access ``T`` parameter is passed as a ``BY REFERENCE`` data item of
945 the COBOL type corresponding to ``T``."
946
947 Followed.
948
949 "An Ada in scalar parameter is passed as a ``BY CONTENT`` data item of
950 the corresponding COBOL type."
951
952 Followed.
953
954 "Any other Ada parameter is passed as a ``BY REFERENCE`` data item of the
955 COBOL type corresponding to the Ada parameter type; for scalars, a local
956 copy is used if necessary to ensure by-copy semantics."
957
958 Followed.
959
960 .. index:: Fortran, interfacing with
961
962 RM B.5(22-26): Interfacing with Fortran
963 =======================================
964
965 "An Ada implementation should support the following interface
966 correspondences between Ada and Fortran:"
967
968 Followed.
969
970 "An Ada procedure corresponds to a Fortran subroutine."
971
972 Followed.
973
974 "An Ada function corresponds to a Fortran function."
975
976 Followed.
977
978 "An Ada parameter of an elementary, array, or record type ``T`` is
979 passed as a ``T`` argument to a Fortran procedure, where ``T`` is
980 the Fortran type corresponding to the Ada type ``T``, and where the
981 INTENT attribute of the corresponding dummy argument matches the Ada
982 formal parameter mode; the Fortran implementation's parameter passing
983 conventions are used. For elementary types, a local copy is used if
984 necessary to ensure by-copy semantics."
985
986 Followed.
987
988 "An Ada parameter of an access-to-subprogram type is passed as a
989 reference to a Fortran procedure whose interface corresponds to the
990 designated subprogram's specification."
991
992 Followed.
993
994 .. index:: Machine operations
995
996 RM C.1(3-5): Access to Machine Operations
997 =========================================
998
999 "The machine code or intrinsic support should allow access to all
1000 operations normally available to assembly language programmers for the
1001 target environment, including privileged instructions, if any."
1002
1003 Followed.
1004
1005 "The interfacing pragmas (see Annex B) should support interface to
1006 assembler; the default assembler should be associated with the
1007 convention identifier ``Assembler``."
1008
1009 Followed.
1010
1011 "If an entity is exported to assembly language, then the implementation
1012 should allocate it at an addressable location, and should ensure that it
1013 is retained by the linking process, even if not otherwise referenced
1014 from the Ada code. The implementation should assume that any call to a
1015 machine code or assembler subprogram is allowed to read or update every
1016 object that is specified as exported."
1017
1018 Followed.
1019
1020 RM C.1(10-16): Access to Machine Operations
1021 ===========================================
1022
1023 "The implementation should ensure that little or no overhead is
1024 associated with calling intrinsic and machine-code subprograms."
1025
1026 Followed for both intrinsics and machine-code subprograms.
1027
1028 "It is recommended that intrinsic subprograms be provided for convenient
1029 access to any machine operations that provide special capabilities or
1030 efficiency and that are not otherwise available through the language
1031 constructs."
1032
1033 Followed. A full set of machine operation intrinsic subprograms is provided.
1034
1035 "Atomic read-modify-write operations---e.g., test and set, compare and
1036 swap, decrement and test, enqueue/dequeue."
1037
1038 Followed on any target supporting such operations.
1039
1040 "Standard numeric functions---e.g.:, sin, log."
1041
1042 Followed on any target supporting such operations.
1043
1044 "String manipulation operations---e.g.:, translate and test."
1045
1046 Followed on any target supporting such operations.
1047
1048 "Vector operations---e.g.:, compare vector against thresholds."
1049
1050 Followed on any target supporting such operations.
1051
1052 "Direct operations on I/O ports."
1053
1054 Followed on any target supporting such operations.
1055
1056 .. index:: Interrupt support
1057
1058 RM C.3(28): Interrupt Support
1059 =============================
1060
1061 "If the ``Ceiling_Locking`` policy is not in effect, the
1062 implementation should provide means for the application to specify which
1063 interrupts are to be blocked during protected actions, if the underlying
1064 system allows for a finer-grain control of interrupt blocking."
1065
1066 Followed. The underlying system does not allow for finer-grain control
1067 of interrupt blocking.
1068
1069 .. index:: Protected procedure handlers
1070
1071 RM C.3.1(20-21): Protected Procedure Handlers
1072 =============================================
1073
1074 "Whenever possible, the implementation should allow interrupt handlers to
1075 be called directly by the hardware."
1076
1077 Followed on any target where the underlying operating system permits
1078 such direct calls.
1079
1080 "Whenever practical, violations of any
1081 implementation-defined restrictions should be detected before run time."
1082
1083 Followed. Compile time warnings are given when possible.
1084
1085 .. index:: Package ``Interrupts``
1086
1087 .. index:: Interrupts
1088
1089 RM C.3.2(25): Package ``Interrupts``
1090 ====================================
1091
1092 "If implementation-defined forms of interrupt handler procedures are
1093 supported, such as protected procedures with parameters, then for each
1094 such form of a handler, a type analogous to ``Parameterless_Handler``
1095 should be specified in a child package of ``Interrupts``, with the
1096 same operations as in the predefined package Interrupts."
1097
1098 Followed.
1099
1100 .. index:: Pre-elaboration requirements
1101
1102 RM C.4(14): Pre-elaboration Requirements
1103 ========================================
1104
1105 "It is recommended that pre-elaborated packages be implemented in such a
1106 way that there should be little or no code executed at run time for the
1107 elaboration of entities not already covered by the Implementation
1108 Requirements."
1109
1110 Followed. Executable code is generated in some cases, e.g., loops
1111 to initialize large arrays.
1112
1113 RM C.5(8): Pragma ``Discard_Names``
1114 ===================================
1115
1116 "If the pragma applies to an entity, then the implementation should
1117 reduce the amount of storage used for storing names associated with that
1118 entity."
1119
1120 Followed.
1121
1122 .. index:: Package Task_Attributes
1123
1124 .. index:: Task_Attributes
1125
1126 RM C.7.2(30): The Package Task_Attributes
1127 =========================================
1128
1129 "Some implementations are targeted to domains in which memory use at run
1130 time must be completely deterministic. For such implementations, it is
1131 recommended that the storage for task attributes will be pre-allocated
1132 statically and not from the heap. This can be accomplished by either
1133 placing restrictions on the number and the size of the task's
1134 attributes, or by using the pre-allocated storage for the first ``N``
1135 attribute objects, and the heap for the others. In the latter case,
1136 ``N`` should be documented."
1137
1138 Not followed. This implementation is not targeted to such a domain.
1139
1140 .. index:: Locking Policies
1141
1142 RM D.3(17): Locking Policies
1143 ============================
1144
1145 "The implementation should use names that end with ``_Locking`` for
1146 locking policies defined by the implementation."
1147
1148 Followed. Two implementation-defined locking policies are defined,
1149 whose names (``Inheritance_Locking`` and
1150 ``Concurrent_Readers_Locking``) follow this suggestion.
1151
1152 .. index:: Entry queuing policies
1153
1154 RM D.4(16): Entry Queuing Policies
1155 ==================================
1156
1157 "Names that end with ``_Queuing`` should be used
1158 for all implementation-defined queuing policies."
1159
1160 Followed. No such implementation-defined queuing policies exist.
1161
1162 .. index:: Preemptive abort
1163
1164 RM D.6(9-10): Preemptive Abort
1165 ==============================
1166
1167 "Even though the *abort_statement* is included in the list of
1168 potentially blocking operations (see 9.5.1), it is recommended that this
1169 statement be implemented in a way that never requires the task executing
1170 the *abort_statement* to block."
1171
1172 Followed.
1173
1174 "On a multi-processor, the delay associated with aborting a task on
1175 another processor should be bounded; the implementation should use
1176 periodic polling, if necessary, to achieve this."
1177
1178 Followed.
1179
1180 .. index:: Tasking restrictions
1181
1182 RM D.7(21): Tasking Restrictions
1183 ================================
1184
1185 "When feasible, the implementation should take advantage of the specified
1186 restrictions to produce a more efficient implementation."
1187
1188 GNAT currently takes advantage of these restrictions by providing an optimized
1189 run time when the Ravenscar profile and the GNAT restricted run time set
1190 of restrictions are specified. See pragma ``Profile (Ravenscar)`` and
1191 pragma ``Profile (Restricted)`` for more details.
1192
1193 .. index:: Time, monotonic
1194
1195 RM D.8(47-49): Monotonic Time
1196 =============================
1197
1198 "When appropriate, implementations should provide configuration
1199 mechanisms to change the value of ``Tick``."
1200
1201 Such configuration mechanisms are not appropriate to this implementation
1202 and are thus not supported.
1203
1204 "It is recommended that ``Calendar.Clock`` and ``Real_Time.Clock``
1205 be implemented as transformations of the same time base."
1206
1207 Followed.
1208
1209
1210 "It is recommended that the best time base which exists in
1211 the underlying system be available to the application through
1212 ``Clock``. `Best` may mean highest accuracy or largest range."
1213
1214 Followed.
1215
1216 .. index:: Partition communication subsystem
1217
1218 .. index:: PCS
1219
1220 RM E.5(28-29): Partition Communication Subsystem
1221 ================================================
1222
1223 "Whenever possible, the PCS on the called partition should allow for
1224 multiple tasks to call the RPC-receiver with different messages and
1225 should allow them to block until the corresponding subprogram body
1226 returns."
1227
1228 Followed by GLADE, a separately supplied PCS that can be used with
1229 GNAT.
1230
1231 "The ``Write`` operation on a stream of type ``Params_Stream_Type``
1232 should raise ``Storage_Error`` if it runs out of space trying to
1233 write the ``Item`` into the stream."
1234
1235 Followed by GLADE, a separately supplied PCS that can be used with
1236 GNAT.
1237
1238 .. index:: COBOL support
1239
1240 RM F(7): COBOL Support
1241 ======================
1242
1243 "If COBOL (respectively, C) is widely supported in the target
1244 environment, implementations supporting the Information Systems Annex
1245 should provide the child package ``Interfaces.COBOL`` (respectively,
1246 ``Interfaces.C``) specified in Annex B and should support a
1247 ``convention_identifier`` of COBOL (respectively, C) in the interfacing
1248 pragmas (see Annex B), thus allowing Ada programs to interface with
1249 programs written in that language."
1250
1251 Followed.
1252
1253 .. index:: Decimal radix support
1254
1255 RM F.1(2): Decimal Radix Support
1256 ================================
1257
1258 "Packed decimal should be used as the internal representation for objects
1259 of subtype ``S`` when ``S``'Machine_Radix = 10."
1260
1261 Not followed. GNAT ignores ``S``'Machine_Radix and always uses binary
1262 representations.
1263
1264 .. index:: Numerics
1265
1266 RM G: Numerics
1267 ==============
1268
1269 "If Fortran (respectively, C) is widely supported in the target
1270 environment, implementations supporting the Numerics Annex
1271 should provide the child package ``Interfaces.Fortran`` (respectively,
1272 ``Interfaces.C``) specified in Annex B and should support a
1273 ``convention_identifier`` of Fortran (respectively, C) in the interfacing
1274 pragmas (see Annex B), thus allowing Ada programs to interface with
1275 programs written in that language."
1276
1277 Followed.
1278
1279 .. index:: Complex types
1280
1281 RM G.1.1(56-58): Complex Types
1282 ==============================
1283
1284 "Because the usual mathematical meaning of multiplication of a complex
1285 operand and a real operand is that of the scaling of both components of
1286 the former by the latter, an implementation should not perform this
1287 operation by first promoting the real operand to complex type and then
1288 performing a full complex multiplication. In systems that, in the
1289 future, support an Ada binding to IEC 559:1989, the latter technique
1290 will not generate the required result when one of the components of the
1291 complex operand is infinite. (Explicit multiplication of the infinite
1292 component by the zero component obtained during promotion yields a NaN
1293 that propagates into the final result.) Analogous advice applies in the
1294 case of multiplication of a complex operand and a pure-imaginary
1295 operand, and in the case of division of a complex operand by a real or
1296 pure-imaginary operand."
1297
1298 Not followed.
1299
1300 "Similarly, because the usual mathematical meaning of addition of a
1301 complex operand and a real operand is that the imaginary operand remains
1302 unchanged, an implementation should not perform this operation by first
1303 promoting the real operand to complex type and then performing a full
1304 complex addition. In implementations in which the ``Signed_Zeros``
1305 attribute of the component type is ``True`` (and which therefore
1306 conform to IEC 559:1989 in regard to the handling of the sign of zero in
1307 predefined arithmetic operations), the latter technique will not
1308 generate the required result when the imaginary component of the complex
1309 operand is a negatively signed zero. (Explicit addition of the negative
1310 zero to the zero obtained during promotion yields a positive zero.)
1311 Analogous advice applies in the case of addition of a complex operand
1312 and a pure-imaginary operand, and in the case of subtraction of a
1313 complex operand and a real or pure-imaginary operand."
1314
1315 Not followed.
1316
1317 "Implementations in which ``Real'Signed_Zeros`` is ``True`` should
1318 attempt to provide a rational treatment of the signs of zero results and
1319 result components. As one example, the result of the ``Argument``
1320 function should have the sign of the imaginary component of the
1321 parameter ``X`` when the point represented by that parameter lies on
1322 the positive real axis; as another, the sign of the imaginary component
1323 of the ``Compose_From_Polar`` function should be the same as
1324 (respectively, the opposite of) that of the ``Argument`` parameter when that
1325 parameter has a value of zero and the ``Modulus`` parameter has a
1326 nonnegative (respectively, negative) value."
1327
1328 Followed.
1329
1330 .. index:: Complex elementary functions
1331
1332 RM G.1.2(49): Complex Elementary Functions
1333 ==========================================
1334
1335 "Implementations in which ``Complex_Types.Real'Signed_Zeros`` is
1336 ``True`` should attempt to provide a rational treatment of the signs
1337 of zero results and result components. For example, many of the complex
1338 elementary functions have components that are odd functions of one of
1339 the parameter components; in these cases, the result component should
1340 have the sign of the parameter component at the origin. Other complex
1341 elementary functions have zero components whose sign is opposite that of
1342 a parameter component at the origin, or is always positive or always
1343 negative."
1344
1345 Followed.
1346
1347 .. index:: Accuracy requirements
1348
1349 RM G.2.4(19): Accuracy Requirements
1350 ===================================
1351
1352 "The versions of the forward trigonometric functions without a
1353 ``Cycle`` parameter should not be implemented by calling the
1354 corresponding version with a ``Cycle`` parameter of
1355 ``2.0*Numerics.Pi``, since this will not provide the required
1356 accuracy in some portions of the domain. For the same reason, the
1357 version of ``Log`` without a ``Base`` parameter should not be
1358 implemented by calling the corresponding version with a ``Base``
1359 parameter of ``Numerics.e``."
1360
1361 Followed.
1362
1363 .. index:: Complex arithmetic accuracy
1364
1365 .. index:: Accuracy, complex arithmetic
1366
1367 RM G.2.6(15): Complex Arithmetic Accuracy
1368 =========================================
1369
1370 "The version of the ``Compose_From_Polar`` function without a
1371 ``Cycle`` parameter should not be implemented by calling the
1372 corresponding version with a ``Cycle`` parameter of
1373 ``2.0*Numerics.Pi``, since this will not provide the required
1374 accuracy in some portions of the domain."
1375
1376 Followed.
1377
1378 .. index:: Sequential elaboration policy
1379
1380 RM H.6(15/2): Pragma Partition_Elaboration_Policy
1381 =================================================
1382
1383 "If the partition elaboration policy is ``Sequential`` and the
1384 Environment task becomes permanently blocked during elaboration then the
1385 partition is deadlocked and it is recommended that the partition be
1386 immediately terminated."
1387
1388 Not followed.