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