3. Implementation Advice

In addition, there are sections throughout the Ada 95 reference manual headed by the phrase "implementation advice". These sections are not normative, i.e. they do not specify requirements that all compilers must follow. Rather they provide advice on generally desirable behavior. You may wonder why they are not requirements. The most typical answer is that they describe behavior that seems generally desirable, but cannot be provided on all systems, or which may be undesirable on some systems.

As far as practical, GNAT follows the implementation advice sections in the Ada 95 Reference Manual. This chapter contains a table giving the reference manual section number, paragraph number and several keywords for each advice. Each entry consists of the text of the advice followed by the GNAT interpretation of this advice. Most often, this simply says "followed", which means that GNAT follows the advice. However, in a number of cases, GNAT deliberately deviates from this advice, in which case the text describes what GNAT does and why.

1.1.3(20): Error Detection

1.1.3(31): Child Units

1.1.5(12): Bounded Errors

2.8(16): Pragmas

Abort_Defer

Affects semantics

Ada_83

Affects legality

Assert

Affects semantics

CPP_Class

Affects semantics

CPP_Constructor

Affects semantics

CPP_Virtual

Affects semantics

CPP_Vtable

Affects semantics

Debug

Affects semantics

Interface_Name

Affects semantics

Machine_Attribute

Affects semantics

Unimplemented_Unit

Affects legality

Unchecked_Union

Affects semantics

In each of the above cases, it is essential to the purpose of the pragma that this advice not be followed. For details see the separate section on implementation defined pragmas.

2.8(17-19): Pragmas

3.5.2(5): Alternative Character Sets

3.5.4(28): Integer Types

An implementation should support Long_Integer in addition to Integer if the target machine supports 32-bit (or longer) arithmetic. No other named integer subtypes are recommended for package Standard. Instead, appropriate named integer subtypes should be provided in the library package Interfaces (see B.2). Long_Integer is supported. Other standard integer types are supported so this advice is not fully followed. These types are supported for convenient interface to C, and so that all hardware types of the machine are easily available.

3.5.4(29): Integer Types

An implementation for a two's complement machine should support modular types with a binary modulus up to System.Max_Int*2+2. An implementation should support a non-binary modules up to Integer'Last. Followed.

3.5.5(8): Enumeration Values

3.5.7(17): Float Types

3.6.2(11): Multidimensional Arrays

9.6(30-31): Duration'Small

The time base for delay_relative_statements should be monotonic; it need not be the same time base as used for Calendar.Clock. Followed.

10.2.1(12): Consistent Representation

11.4.1(19): Exception Information

11.5(28): Suppression of Checks

13.1 (21-24): Representation Clauses

X : Integer; Y : Float; for Y'Address use X'Address;>>

An implementation need not support a specification for the Size for a given composite subtype, nor the size or storage place for an object (including a component) of a given composite subtype, unless the constraints on the subtype and its composite subcomponents (if any) are all static constraints. Followed. Size Clauses are not permitted on non-static components, as described above.

An aliased component, or a component whose type is by-reference, should always be allocated at an addressable location. Followed.

13.2(6-8): Packed Types

For a packed record type, the components should be packed as tightly as possible subject to the Sizes of the component subtypes, and subject to any record_representation_clause that applies to the type; the implementation may, but need not, reorder components or cross aligned word boundaries to improve the packing. A component whose Size is greater than the word size may be allocated an integral number of words. Followed. Tight packing of arrays is supported for all component sizes up to 64-bits. If the array component size is 1 (that is to say, if the component is a boolean type or an enumeration type with two values) then values of the type are implicitly initialized to zero. This happens both for objects of the packed type, and for objects that have a subcomponent of the packed type.

An implementation should support Address clauses for imported subprograms. Followed.

13.3(14-19): Address Clauses

For an array X, X'Address should point at the first component of the array, and not at the array bounds. Followed.

The recommended level of support for the Address attribute is:

X'Address should produce a useful result if X is an object that is aliased or of a by-reference type, or is an entity whose Address has been specified. Followed. A valid address will be produced even if none of those conditions have been met. If necessary, the object is forced into memory to ensure the address is valid.

An implementation should support Address clauses for imported subprograms. Followed.

Objects (including subcomponents) that are aliased or of a by-reference type should be allocated on storage element boundaries. Followed.

If the Address of an object is specified, or it is imported or exported, then the implementation should not perform optimizations based on assumptions of no aliases. Followed.

13.3(29-35): Alignment Clauses

An implementation should support specified Alignments that are factors and multiples of the number of storage elements per word, subject to the following: Followed.

An implementation need not support specified Alignments for combinations of Sizes and Alignments that cannot be easily loaded and stored by available machine instructions. Followed.

An implementation need not support specified Alignments that are greater than the maximum Alignment the implementation ever returns by default. Followed.

The recommended level of support for the Alignment attribute for objects is:

Same as above, for subtypes, but in addition: Followed.

For stand-alone library-level objects of statically constrained subtypes, the implementation should support all Alignments supported by the target linker. For example, page alignment is likely to be supported for such objects, but not for subtypes. Followed.

13.3(42-43): Size Clauses

A Size clause should be supported for an object if the specified Size is at least as large as its subtype's Size, and corresponds to a size in storage elements that is a multiple of the object's Alignment (if the Alignment is nonzero). Followed.

13.3(50-56): Size Clauses

Aliased objects (including components). Followed.

Size clause on a composite subtype should not affect the internal layout of components. Followed.

The recommended level of support for the Size attribute of subtypes is: The Size (if not specified) of a static discrete or fixed point subtype should be the number of bits needed to represent each value belonging to the subtype using an unbiased representation, leaving space for a sign bit only if the subtype contains negative values. If such a subtype is a first subtype, then an implementation should support a specified Size for it that reflects this representation. Followed.

For a subtype implemented with levels of indirection, the Size should include the size of the pointers, but not the size of what they point at. Followed.

13.3(71-73): Component Size Clauses

An implementation should support specified Component_Sizes that are factors and multiples of the word size. For such Component_Sizes, the array should contain no gaps between components. For other Component_Sizes (if supported), the array should contain no gaps between components when packing is also specified; the implementation should forbid this combination in cases where it cannot support a no-gaps representation. Followed.

13.4(9-10): Enumeration Representation Clauses

An implementation need not support enumeration representation clauses for boolean types, but should at minimum support the internal codes in the range System.Min_Int.System.Max_Int. Followed.

13.5.1(17-22): Record Representation Clauses

An implementation should support storage places that can be extracted with a load, mask, shift sequence of machine code, and set with a load, shift, mask, store sequence, given the available machine instructions and run-time model. Followed.

A storage place should be supported if its size is equal to the Size of the component subtype, and it starts and ends on a boundary that obeys the Alignment of the component subtype. Followed.

If the default bit ordering applies to the declaration of a given type, then for a component whose subtype's Size is less than the word size, any storage place that does not cross an aligned word boundary should be supported. Followed.

An implementation may reserve a storage place for the tag field of a tagged type, and disallow other components from overlapping that place. Followed. The storage place for the tag field is the beginning of the tagged record, and its size is Address'Size. GNAT will reject an explicit component clause for the tag field.

An implementation need not support a component_clause for a component of an extension part if the storage place is not after the storage places of all components of the parent type, whether or not those storage places had been specified. Followed. The above advice on record representation clauses is followed, and all mentioned features are implemented.

13.5.2(5): Storage Place Attributes

13.5.3(7-8): Bit Ordering

13.7(37): Address as Private

13.7.1(16): Address Operations

13.9(14-17): Unchecked Conversion

The implementation should not generate unnecessary run-time checks to ensure that the representation of S is a representation of the target type. It should take advantage of the permission to return by reference when possible. Restrictions on unchecked conversions should be avoided unless required by the target environment. Followed. There are no restrictions on unchecked conversion. A warning is generated if the source and target types do not have the same size since the semantics in this case may be target dependent.

The recommended level of support for unchecked conversions is: Unchecked conversions should be supported and should be reversible in the cases where this clause defines the result. To enable meaningful use of unchecked conversion, a contiguous representation should be used for elementary subtypes, for statically constrained array subtypes whose component subtype is one of the subtypes described in this paragraph, and for record subtypes without discriminants whose component subtypes are described in this paragraph. Followed.

13.11(23-25): Implicit Heap Usage

• At initial elaboration time, to allocate dynamically sized global objects.

• To allocate space for a task when a task is created.

• To extend the secondary stack dynamically when needed. The secondary stack is used for returning variable length results.

A default (implementation-provided) storage pool for an access-to-constant type should not have overhead to support deallocation of individual objects. Followed.

A storage pool for an anonymous access type should be created at the point of an allocator for the type, and be reclaimed when the designated object becomes inaccessible. Followed.

13.11.2(17): Unchecked De-allocation

13.13.2(17): Stream Oriented Attributes

Followed. By default, GNAT uses the interpretation suggested by AI-195, which specifies using the size of the first subtype. However, such an implementation is based on direct binary representations and is therefore target- and endianness-dependent. To address this issue, GNAT also supplies an alternate implementation of the stream attributes Read and Write, which uses the target-independent XDR standard representation for scalar types. The XDR implementation is provided as an alternative body of the System.Stream_Attributes package, in the file `s-strxdr.adb' in the GNAT library. There is no `s-strxdr.ads' file. In order to install the XDR implementation, do the following:

1. Replace the default implementation of the System.Stream_Attributes package with the XDR implementation. For example on a Unix platform issue the commands:

   $ mv s-stratt.adb s-strold.adb $ mv s-strxdr.adb s-stratt.adb

2. Rebuild the GNAT run-time library as documented in the GNAT User's Guide

A.1(52): Names of Predefined Numeric Types

A.3.2(49): Ada.Characters.Handling

A.4.4(106): Bounded-Length String Handling

A.5.2(46-47): Random Number Generation

If the generator period is sufficiently long in relation to the number of distinct initiator values, then each possible value of Initiator passed to Reset should initiate a sequence of random numbers that does not, in a practical sense, overlap the sequence initiated by any other value. If this is not possible, then the mapping between initiator values and generator states should be a rapidly varying function of the initiator value. Followed. The generator period is sufficiently long for the first condition here to hold true.

A.10.7(23): Get_Immediate

B.1(39-41): Pragma Export

Automatic elaboration of pre-elaborated packages should be provided when pragma Export is supported. Followed when the main program is in Ada. If the main program is in a foreign language, then adainit must be called to elaborate pre-elaborated packages.

For each supported convention L other than Intrinsic, an implementation should support Import and Export pragmas for objects of L-compatible types and for subprograms, and pragma Convention for L-eligible types and for subprograms, presuming the other language has corresponding features. Pragma Convention need not be supported for scalar types. Followed.

B.2(12-13): Package Interfaces

An implementation supporting an interface to C, COBOL, or Fortran should provide the corresponding package or packages described in the following clauses. Followed. GNAT provides all the packages described in this section.

B.3(63-71): Interfacing with C

An Ada procedure corresponds to a void-returning C function. Followed.

An Ada function corresponds to a non-void C function. Followed.

An Ada in scalar parameter is passed as a scalar argument to a C function. Followed.

An Ada in parameter of an access-to-object type with designated type T is passed as a t* argument to a C function, where t is the C type corresponding to the Ada type T. Followed.

An Ada access T parameter, or an Ada out or in out parameter of an elementary type T, is passed as a t* argument to a C function, where t is the C type corresponding to the Ada type T. In the case of an elementary out or in out parameter, a pointer to a temporary copy is used to preserve by-copy semantics. Followed.

An Ada parameter of a record type T, of any mode, is passed as a t* argument to a C function, where t is the C structure corresponding to the Ada type T. Followed. This convention may be overridden by the use of the C_Pass_By_Copy pragma, or Convention, or by explicitly specifying the mechanism for a given call using an extended import or export pragma.

An Ada parameter of an array type with component type T, of any mode, is passed as a t* argument to a C function, where t is the C type corresponding to the Ada type T. Followed.

An Ada parameter of an access-to-subprogram type is passed as a pointer to a C function whose prototype corresponds to the designated subprogram's specification. Followed.

B.4(95-98): Interfacing with COBOL

An Ada access T parameter is passed as a `BY REFERENCE' data item of the COBOL type corresponding to T. Followed.

An Ada in scalar parameter is passed as a `BY CONTENT' data item of the corresponding COBOL type. Followed.

Any other Ada parameter is passed as a `BY REFERENCE' data item of the COBOL type corresponding to the Ada parameter type; for scalars, a local copy is used if necessary to ensure by-copy semantics. Followed.

B.5(22-26): Interfacing with Fortran

An Ada procedure corresponds to a Fortran subroutine. Followed.

An Ada function corresponds to a Fortran function. Followed.

An Ada parameter of an elementary, array, or record type T is passed as a T argument to a Fortran procedure, where T is the Fortran type corresponding to the Ada type T, and where the INTENT attribute of the corresponding dummy argument matches the Ada formal parameter mode; the Fortran implementation's parameter passing conventions are used. For elementary types, a local copy is used if necessary to ensure by-copy semantics. Followed.

An Ada parameter of an access-to-subprogram type is passed as a reference to a Fortran procedure whose interface corresponds to the designated subprogram's specification. Followed.

C.1(3-5): Access to Machine Operations

The interfacing pragmas (see Annex B) should support interface to assembler; the default assembler should be associated with the convention identifier Assembler. Followed.

If an entity is exported to assembly language, then the implementation should allocate it at an addressable location, and should ensure that it is retained by the linking process, even if not otherwise referenced from the Ada code. The implementation should assume that any call to a machine code or assembler subprogram is allowed to read or update every object that is specified as exported. Followed.

C.1(10-16): Access to Machine Operations

It is recommended that intrinsic subprograms be provided for convenient access to any machine operations that provide special capabilities or efficiency and that are not otherwise available through the language constructs. Followed. A full set of machine operation intrinsic subprograms is provided.

Atomic read-modify-write operations--e.g., test and set, compare and swap, decrement and test, enqueue/dequeue. Followed on any target supporting such operations.

Standard numeric functions--e.g., sin, log. Followed on any target supporting such operations.

String manipulation operations--e.g., translate and test. Followed on any target supporting such operations.

Vector operations--e.g., compare vector against thresholds. Followed on any target supporting such operations.

Direct operations on I/O ports. Followed on any target supporting such operations.

C.3(28): Interrupt Support

C.3.1(20-21): Protected Procedure Handlers

Whenever practical, violations of any implementation-defined restrictions should be detected before run time. Followed. Compile time warnings are given when possible.

C.3.2(25): Package Interrupts

If implementation-defined forms of interrupt handler procedures are supported, such as protected procedures with parameters, then for each such form of a handler, a type analogous to Parameterless_Handler should be specified in a child package of Interrupts, with the same operations as in the predefined package Interrupts. Followed.

C.4(14): Pre-elaboration Requirements

C.5(8): Pragma Discard_Names

If the pragma applies to an entity, then the implementation should reduce the amount of storage used for storing names associated with that entity. Followed.

C.7.2(30): The Package Task_Attributes

D.3(17): Locking Policies

The implementation should use names that end with `_Locking' for locking policies defined by the implementation. Followed. A single implementation-defined locking policy is defined, whose name (Inheritance_Locking) follows this suggestion.

D.4(16): Entry Queuing Policies

D.6(9-10): Preemptive Abort

On a multi-processor, the delay associated with aborting a task on another processor should be bounded; the implementation should use periodic polling, if necessary, to achieve this. Followed.

D.7(21): Tasking Restrictions

D.8(47-49): Monotonic Time

It is recommended that Calendar.Clock and Real_Time.Clock be implemented as transformations of the same time base. Followed.

It is recommended that the best time base which exists in the underlying system be available to the application through Clock. Best may mean highest accuracy or largest range. Followed.

E.5(28-29): Partition Communication Subsystem

The Write operation on a stream of type Params_Stream_Type should raise Storage_Error if it runs out of space trying to write the Item into the stream. Followed by GLADE, a separately supplied PCS that can be used with GNAT.

F(7): COBOL Support

F.1(2): Decimal Radix Support

G: Numerics

G.1.1(56-58): Complex Types

Similarly, because the usual mathematical meaning of addition of a complex operand and a real operand is that the imaginary operand remains unchanged, an implementation should not perform this operation by first promoting the real operand to complex type and then performing a full complex addition. In implementations in which the Signed_Zeros attribute of the component type is True (and which therefore conform to IEC 559:1989 in regard to the handling of the sign of zero in predefined arithmetic operations), the latter technique will not generate the required result when the imaginary component of the complex operand is a negatively signed zero. (Explicit addition of the negative zero to the zero obtained during promotion yields a positive zero.) Analogous advice applies in the case of addition of a complex operand and a pure-imaginary operand, and in the case of subtraction of a complex operand and a real or pure-imaginary operand. Not followed.

Implementations in which Real'Signed_Zeros is True should attempt to provide a rational treatment of the signs of zero results and result components. As one example, the result of the Argument function should have the sign of the imaginary component of the parameter X when the point represented by that parameter lies on the positive real axis; as another, the sign of the imaginary component of the Compose_From_Polar function should be the same as (respectively, the opposite of) that of the Argument parameter when that parameter has a value of zero and the Modulus parameter has a nonnegative (respectively, negative) value. Followed.

G.1.2(49): Complex Elementary Functions

G.2.4(19): Accuracy Requirements

G.2.6(15): Complex Arithmetic Accuracy

The version of the Compose_From_Polar function without a Cycle parameter should not be implemented by calling the corresponding version with a Cycle parameter of 2.0*Numerics.Pi, since this will not provide the required accuracy in some portions of the domain. Followed.